diff options
Diffstat (limited to 'doc/languages-frameworks')
| -rw-r--r-- | doc/languages-frameworks/android.section.md | 144 | ||||
| -rw-r--r-- | doc/languages-frameworks/dart.section.md | 6 | ||||
| -rw-r--r-- | doc/languages-frameworks/dotnet.section.md | 15 | ||||
| -rw-r--r-- | doc/languages-frameworks/hare.section.md | 53 | ||||
| -rw-r--r-- | doc/languages-frameworks/haskell.section.md | 148 | ||||
| -rw-r--r-- | doc/languages-frameworks/idris2.section.md | 8 | ||||
| -rw-r--r-- | doc/languages-frameworks/index.md | 49 | ||||
| -rw-r--r-- | doc/languages-frameworks/javascript.section.md | 65 | ||||
| -rw-r--r-- | doc/languages-frameworks/nim.section.md | 6 | ||||
| -rw-r--r-- | doc/languages-frameworks/ocaml.section.md | 8 | ||||
| -rw-r--r-- | doc/languages-frameworks/python.section.md | 111 | ||||
| -rw-r--r-- | doc/languages-frameworks/rust.section.md | 14 | ||||
| -rw-r--r-- | doc/languages-frameworks/vim.section.md | 2 |
13 files changed, 405 insertions, 224 deletions
diff --git a/doc/languages-frameworks/android.section.md b/doc/languages-frameworks/android.section.md index 1c5687f8ebf1b..db4aea04e5e09 100644 --- a/doc/languages-frameworks/android.section.md +++ b/doc/languages-frameworks/android.section.md @@ -3,10 +3,36 @@ The Android build environment provides three major features and a number of supporting features. +## Using androidenv with Android Studio {#using-androidenv-with-android-studio} + +Use the `android-studio-full` attribute for a very complete Android SDK, including system images: + +```nix +buildInputs = [ android-studio-full ]; +``` + +This is identical to: + +```nix +buildInputs = [ androidStudioPackages.stable.full ]; +``` + +Alternatively, you can pass composeAndroidPackages to the `withSdk` passthru: + +```nix +buildInputs = [ + (android-studio.withSdk (androidenv.composeAndroidPackages { + includeNDK = true; + }).androidsdk) +]; +``` + +These will export ANDROID_SDK_ROOT and ANDROID_NDK_ROOT to the SDK and NDK directories +in the specified Android build environment. + ## Deploying an Android SDK installation with plugins {#deploying-an-android-sdk-installation-with-plugins} -The first use case is deploying the SDK with a desired set of plugins or subsets -of an SDK. +Alternatively, you can deploy the SDK separately with a desired set of plugins, or subsets of an SDK. ```nix with import <nixpkgs> {}; @@ -145,16 +171,14 @@ androidComposition.platform-tools ## Using predefined Android package compositions {#using-predefined-android-package-compositions} In addition to composing an Android package set manually, it is also possible -to use a predefined composition that contains all basic packages for a specific -Android version, such as version 9.0 (API-level 28). +to use a predefined composition that contains a fairly complete set of Android packages: -The following Nix expression can be used to deploy the entire SDK with all basic -plugins: +The following Nix expression can be used to deploy the entire SDK: ```nix with import <nixpkgs> {}; -androidenv.androidPkgs_9_0.androidsdk +androidenv.androidPkgs.androidsdk ``` It is also possible to use one plugin only: @@ -162,50 +186,9 @@ It is also possible to use one plugin only: ```nix with import <nixpkgs> {}; -androidenv.androidPkgs_9_0.platform-tools -``` - -## Building an Android application {#building-an-android-application} - -In addition to the SDK, it is also possible to build an Ant-based Android -project and automatically deploy all the Android plugins that a project -requires. - - -```nix -with import <nixpkgs> {}; - -androidenv.buildApp { - name = "MyAndroidApp"; - src = ./myappsources; - release = true; - - # If release is set to true, you need to specify the following parameters - keyStore = ./keystore; - keyAlias = "myfirstapp"; - keyStorePassword = "mykeystore"; - keyAliasPassword = "myfirstapp"; - - # Any Android SDK parameters that install all the relevant plugins that a - # build requires - platformVersions = [ "24" ]; - - # When we include the NDK, then ndk-build is invoked before Ant gets invoked - includeNDK = true; -} +androidenv.androidPkgs.platform-tools ``` -Aside from the app-specific build parameters (`name`, `src`, `release` and -keystore parameters), the `buildApp {}` function supports all the function -parameters that the SDK composition function (the function shown in the -previous section) supports. - -This build function is particularly useful when it is desired to use -[Hydra](https://nixos.org/hydra): the Nix-based continuous integration solution -to build Android apps. An Android APK gets exposed as a build product and can be -installed on any Android device with a web browser by navigating to the build -result page. - ## Spawning emulator instances {#spawning-emulator-instances} For testing purposes, it can also be quite convenient to automatically generate @@ -249,11 +232,11 @@ In addition to prebuilt APKs, you can also bind the APK parameter to a ## Notes on environment variables in Android projects {#notes-on-environment-variables-in-android-projects} -* `ANDROID_SDK_ROOT` should point to the Android SDK. In your Nix expressions, this should be - `${androidComposition.androidsdk}/libexec/android-sdk`. Note that `ANDROID_HOME` is deprecated, +* `ANDROID_HOME` should point to the Android SDK. In your Nix expressions, this should be + `${androidComposition.androidsdk}/libexec/android-sdk`. Note that `ANDROID_SDK_ROOT` is deprecated, but if you rely on tools that need it, you can export it too. * `ANDROID_NDK_ROOT` should point to the Android NDK, if you're doing NDK development. - In your Nix expressions, this should be `${ANDROID_SDK_ROOT}/ndk-bundle`. + In your Nix expressions, this should be `${ANDROID_HOME}/ndk-bundle`. If you are running the Android Gradle plugin, you need to export GRADLE_OPTS to override aapt2 to point to the aapt2 binary in the Nix store as well, or use a FHS environment so the packaged @@ -267,11 +250,11 @@ let androidComposition = <...>; in pkgs.mkShell rec { - ANDROID_SDK_ROOT = "${androidComposition.androidsdk}/libexec/android-sdk"; - ANDROID_NDK_ROOT = "${ANDROID_SDK_ROOT}/ndk-bundle"; + ANDROID_HOME = "${androidComposition.androidsdk}/libexec/android-sdk"; + ANDROID_NDK_ROOT = "${ANDROID_HOME}/ndk-bundle"; # Use the same buildToolsVersion here - GRADLE_OPTS = "-Dorg.gradle.project.android.aapt2FromMavenOverride=${ANDROID_SDK_ROOT}/build-tools/${buildToolsVersion}/aapt2"; + GRADLE_OPTS = "-Dorg.gradle.project.android.aapt2FromMavenOverride=${ANDROID_HOME}/build-tools/${buildToolsVersion}/aapt2"; } ``` @@ -287,18 +270,18 @@ let androidComposition = <...>; in pkgs.mkShell rec { - ANDROID_SDK_ROOT = "${androidComposition.androidsdk}/libexec/android-sdk"; - ANDROID_NDK_ROOT = "${ANDROID_SDK_ROOT}/ndk-bundle"; + ANDROID_HOME = "${androidComposition.androidsdk}/libexec/android-sdk"; + ANDROID_NDK_ROOT = "${ANDROID_HOME}/ndk-bundle"; # Use the same cmakeVersion here shellHook = '' - export PATH="$(echo "$ANDROID_SDK_ROOT/cmake/${cmakeVersion}".*/bin):$PATH" + export PATH="$(echo "$ANDROID_HOME/cmake/${cmakeVersion}".*/bin):$PATH" ''; } ``` -Note that running Android Studio with ANDROID_SDK_ROOT set will automatically write a -`local.properties` file with `sdk.dir` set to $ANDROID_SDK_ROOT if one does not already +Note that running Android Studio with ANDROID_HOME set will automatically write a +`local.properties` file with `sdk.dir` set to $ANDROID_HOME if one does not already exist. If you are using the NDK as well, you may have to add `ndk.dir` to this file. An example shell.nix that does all this for you is provided in examples/shell.nix. @@ -349,3 +332,44 @@ To update the expressions run the `generate.sh` script that is stored in the ```bash ./generate.sh ``` + +## Building an Android application with Ant {#building-an-android-application-with-ant} + +In addition to the SDK, it is also possible to build an Ant-based Android +project and automatically deploy all the Android plugins that a project +requires. Most newer Android projects use Gradle, and this is included for historical +purposes. + +```nix +with import <nixpkgs> {}; + +androidenv.buildApp { + name = "MyAndroidApp"; + src = ./myappsources; + release = true; + + # If release is set to true, you need to specify the following parameters + keyStore = ./keystore; + keyAlias = "myfirstapp"; + keyStorePassword = "mykeystore"; + keyAliasPassword = "myfirstapp"; + + # Any Android SDK parameters that install all the relevant plugins that a + # build requires + platformVersions = [ "24" ]; + + # When we include the NDK, then ndk-build is invoked before Ant gets invoked + includeNDK = true; +} +``` + +Aside from the app-specific build parameters (`name`, `src`, `release` and +keystore parameters), the `buildApp {}` function supports all the function +parameters that the SDK composition function (the function shown in the +previous section) supports. + +This build function is particularly useful when it is desired to use +[Hydra](https://nixos.org/hydra): the Nix-based continuous integration solution +to build Android apps. An Android APK gets exposed as a build product and can be +installed on any Android device with a web browser by navigating to the build +result page. diff --git a/doc/languages-frameworks/dart.section.md b/doc/languages-frameworks/dart.section.md index 019765f75354c..1b065ff4cde71 100644 --- a/doc/languages-frameworks/dart.section.md +++ b/doc/languages-frameworks/dart.section.md @@ -98,10 +98,12 @@ The function `buildFlutterApplication` builds Flutter applications. See the [Dart documentation](#ssec-dart-applications) for more details on required files and arguments. +`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. + ```nix -{ flutter, fetchFromGitHub }: +{ flutter322, fetchFromGitHub }: -flutter.buildFlutterApplication { +flutter322.buildFlutterApplication { pname = "firmware-updater"; version = "0-unstable-2023-04-30"; diff --git a/doc/languages-frameworks/dotnet.section.md b/doc/languages-frameworks/dotnet.section.md index 36c20a9e9c507..caf213845e6c7 100644 --- a/doc/languages-frameworks/dotnet.section.md +++ b/doc/languages-frameworks/dotnet.section.md @@ -141,9 +141,7 @@ in buildDotnetModule rec { src = ./.; projectFile = "src/project.sln"; - # File generated with `nix-build -A package.passthru.fetch-deps`. - # To run fetch-deps when this file does not yet exist, set nugetDeps to null - nugetDeps = ./deps.nix; + nugetDeps = ./deps.nix; # see "Generating and updating NuGet dependencies" section for details projectReferences = [ referencedProject ]; # `referencedProject` must contain `nupkg` in the folder structure. @@ -219,6 +217,12 @@ buildDotnetGlobalTool { ``` ## Generating and updating NuGet dependencies {#generating-and-updating-nuget-dependencies} +When writing a new expression, you can use the generated `fetch-deps` script to initialise the lockfile. +After creating a blank `deps.nix` and pointing `nugetDeps` to it, +build the script with `nix-build -A package.fetch-deps` and then run the result. +(When the root attr is your package, it's simply `nix-build -A fetch-deps`.) + +There is also a manual method: First, restore the packages to the `out` directory, ensure you have cloned the upstream repository and you are inside it. @@ -254,6 +258,5 @@ Finally, you move the `deps.nix` file to the appropriate location to be used by If you ever need to update the dependencies of a package, you instead do * `nix-build -A package.fetch-deps` to generate the update script for `package` -* Run `./result deps.nix` to regenerate the lockfile to `deps.nix`, keep in mind if a location isn't provided, it will write to a temporary path instead -* Finally, move the file where needed and look at its contents to confirm it has updated the dependencies. - +* Run `./result` to regenerate the lockfile to the path passed for `nugetDeps` (keep in mind if it can't be resolved to a local path, the script will write to `$1` or a temporary path instead) +* Finally, ensure the correct file was written and the derivation can be built. diff --git a/doc/languages-frameworks/hare.section.md b/doc/languages-frameworks/hare.section.md new file mode 100644 index 0000000000000..0ae8abeba45c1 --- /dev/null +++ b/doc/languages-frameworks/hare.section.md @@ -0,0 +1,53 @@ +# Hare {#sec-language-hare} + +## Building Hare programs with `hareHook` {#ssec-language-hare} + +The `hareHook` package sets up the environment for building Hare programs by +doing the following: + +1. Setting the `HARECACHE`, `HAREPATH` and `NIX_HAREFLAGS` environment variables; +1. Propagating `harec`, `qbe` and two wrapper scripts for the hare binary. + +It is not a function as is the case for some other languages --- *e. g.*, Go or +Rust ---, but a package to be added to `nativeBuildInputs`. + +## Attributes of `hareHook` {#hareHook-attributes} + +The following attributes are accepted by `hareHook`: + +1. `hareBuildType`: Either `release` (default) or `debug`. It controls if the + `-R` flag is added to `NIX_HAREFLAGS`. + +## Example for `hareHook` {#ex-hareHook} + +```nix +{ + hareHook, + lib, + stdenv, +}: stdenv.mkDerivation { + pname = "<name>"; + version = "<version>"; + src = "<src>"; + + nativeBuildInputs = [ hareHook ]; + + meta = { + description = "<description>"; + inherit (hareHook) badPlatforms platforms; + }; +} +``` + +## Cross Compilation {#hareHook-cross-compilation} + +`hareHook` should handle cross compilation out of the box. This is the main +purpose of `NIX_HAREFLAGS`: In it, the `-a` flag is passed with the architecture +of the `hostPlatform`. + +However, manual intervention may be needed when a binary compiled by the build +process must be run for the build to complete --- *e. g.*, when using Hare's +`hare` module for code generation. + +In those cases, `hareHook` provides the `hare-native` script, which is a wrapper +around the hare binary for using the native (`buildPlatform`) toolchain. diff --git a/doc/languages-frameworks/haskell.section.md b/doc/languages-frameworks/haskell.section.md index dde55c329a4ac..e8970b2d03354 100644 --- a/doc/languages-frameworks/haskell.section.md +++ b/doc/languages-frameworks/haskell.section.md @@ -21,25 +21,14 @@ Many “normal” user facing packages written in Haskell, like `niv` or `cachix are also exposed at the top level, and there is nothing Haskell specific to installing and using them. -All of these packages are originally defined in the `haskellPackages` package -set and are re-exposed with a reduced dependency closure for convenience. -(see `justStaticExecutables` or `separateBinOutput` below) +All of these packages are originally defined in the `haskellPackages` package set. +The same packages are re-exposed with a reduced dependency closure for convenience (see `justStaticExecutables` or `separateBinOutput` below). -The `haskellPackages` set includes at least one version of every package from -Hackage as well as some manually injected packages. This amounts to a lot of -packages, so it is hidden from `nix-env -qa` by default for performance reasons. -You can still list all packages in the set like this: +:::{.note} +See [](#chap-language-support) for techniques to explore package sets. +::: -```console -$ nix-env -f '<nixpkgs>' -qaP -A haskellPackages -haskellPackages.a50 a50-0.5 -haskellPackages.AAI AAI-0.2.0.1 -haskellPackages.aasam aasam-0.2.0.0 -haskellPackages.abacate abacate-0.0.0.0 -haskellPackages.abc-puzzle abc-puzzle-0.2.1 -… -``` -Also, the `haskellPackages` set is included on [search.nixos.org]. +The `haskellPackages` set includes at least one version of every package from [Hackage](https://hackage.haskell.org/) as well as some manually injected packages. The attribute names in `haskellPackages` always correspond with their name on Hackage. Since Hackage allows names that are not valid Nix without escaping, @@ -49,8 +38,7 @@ For packages that are part of [Stackage] (a curated set of known to be compatible packages), we use the version prescribed by a Stackage snapshot (usually the current LTS one) as the default version. For all other packages we use the latest version from [Hackage](https://hackage.org) (the repository of -basically all open source Haskell packages). See [below](#haskell-available- -versions) for a few more details on this. +basically all open source Haskell packages). See [below](#haskell-available-versions) for a few more details on this. Roughly half of the 16K packages contained in `haskellPackages` don’t actually build and are [marked as broken semi-automatically](https://github.com/NixOS/nixpkgs/blob/haskell-updates/pkgs/development/haskell-modules/configuration-hackage2nix/broken.yaml). @@ -63,68 +51,15 @@ How you can help with that is described in [Fixing a broken package](#haskell-fixing-a-broken-package). --> -`haskellPackages` is built with our default compiler, but we also provide other -releases of GHC and package sets built with them. You can list all available -compilers like this: +`haskellPackages` is built with our default compiler, but we also provide other releases of GHC and package sets built with them. +Available compilers are collected under `haskell.compiler`. -```console -$ nix-env -f '<nixpkgs>' -qaP -A haskell.compiler -haskell.compiler.ghc810 ghc-8.10.7 -haskell.compiler.ghc90 ghc-9.0.2 -haskell.compiler.ghc925 ghc-9.2.5 -haskell.compiler.ghc926 ghc-9.2.6 -haskell.compiler.ghc927 ghc-9.2.7 -haskell.compiler.ghc92 ghc-9.2.8 -haskell.compiler.ghc945 ghc-9.4.5 -haskell.compiler.ghc946 ghc-9.4.6 -haskell.compiler.ghc947 ghc-9.4.7 -haskell.compiler.ghc94 ghc-9.4.8 -haskell.compiler.ghc963 ghc-9.6.3 -haskell.compiler.ghc96 ghc-9.6.4 -haskell.compiler.ghc98 ghc-9.8.1 -haskell.compiler.ghcHEAD ghc-9.9.20231121 -haskell.compiler.ghc8107Binary ghc-binary-8.10.7 -haskell.compiler.ghc865Binary ghc-binary-8.6.5 -haskell.compiler.ghc924Binary ghc-binary-9.2.4 -haskell.compiler.integer-simple.ghc8107 ghc-integer-simple-8.10.7 -haskell.compiler.integer-simple.ghc810 ghc-integer-simple-8.10.7 -haskell.compiler.native-bignum.ghc90 ghc-native-bignum-9.0.2 -haskell.compiler.native-bignum.ghc902 ghc-native-bignum-9.0.2 -haskell.compiler.native-bignum.ghc925 ghc-native-bignum-9.2.5 -haskell.compiler.native-bignum.ghc926 ghc-native-bignum-9.2.6 -haskell.compiler.native-bignum.ghc927 ghc-native-bignum-9.2.7 -haskell.compiler.native-bignum.ghc92 ghc-native-bignum-9.2.8 -haskell.compiler.native-bignum.ghc928 ghc-native-bignum-9.2.8 -haskell.compiler.native-bignum.ghc945 ghc-native-bignum-9.4.5 -haskell.compiler.native-bignum.ghc946 ghc-native-bignum-9.4.6 -haskell.compiler.native-bignum.ghc947 ghc-native-bignum-9.4.7 -haskell.compiler.native-bignum.ghc94 ghc-native-bignum-9.4.8 -haskell.compiler.native-bignum.ghc948 ghc-native-bignum-9.4.8 -haskell.compiler.native-bignum.ghc963 ghc-native-bignum-9.6.3 -haskell.compiler.native-bignum.ghc96 ghc-native-bignum-9.6.4 -haskell.compiler.native-bignum.ghc964 ghc-native-bignum-9.6.4 -haskell.compiler.native-bignum.ghc98 ghc-native-bignum-9.8.1 -haskell.compiler.native-bignum.ghc981 ghc-native-bignum-9.8.1 -haskell.compiler.native-bignum.ghcHEAD ghc-native-bignum-9.9.20231121 -haskell.compiler.ghcjs ghcjs-8.10.7 -``` - -Each of those compiler versions has a corresponding attribute set built using +Each of those compiler versions has a corresponding attribute set `packages` built with it. However, the non-standard package sets are not tested regularly and, as a result, contain fewer working packages. The corresponding package set for GHC 9.4.5 is `haskell.packages.ghc945`. In fact `haskellPackages` is just an alias for `haskell.packages.ghc964`: -```console -$ nix-env -f '<nixpkgs>' -qaP -A haskell.packages.ghc927 -haskell.packages.ghc927.a50 a50-0.5 -haskell.packages.ghc927.AAI AAI-0.2.0.1 -haskell.packages.ghc927.aasam aasam-0.2.0.0 -haskell.packages.ghc927.abacate abacate-0.0.0.0 -haskell.packages.ghc927.abc-puzzle abc-puzzle-0.2.1 -… -``` - Every package set also re-exposes the GHC used to build its packages as `haskell.packages.*.ghc`. ### Available package versions {#haskell-available-versions} @@ -923,14 +858,61 @@ for this to work. `justStaticExecutables drv` : Only build and install the executables produced by `drv`, removing everything -that may refer to other Haskell packages' store paths (like libraries and -documentation). This dramatically reduces the closure size of the resulting -derivation. Note that the executables are only statically linked against their -Haskell dependencies, but will still link dynamically against libc, GMP and -other system library dependencies. If dependencies use their Cabal-generated -`Paths_*` module, this may not work as well if GHC's dead code elimination -is unable to remove the references to the dependency's store path that module -contains. + that may refer to other Haskell packages' store paths (like libraries and + documentation). This dramatically reduces the closure size of the resulting + derivation. Note that the executables are only statically linked against their + Haskell dependencies, but will still link dynamically against libc, GMP and + other system library dependencies. + + If a library or its dependencies use their Cabal-generated + `Paths_*` module, this may not work as well if GHC's dead code elimination is + unable to remove the references to the dependency's store path that module + contains. + As a consequence, an unused reference may be created from the static binary to such a _library_ store path. + (See [nixpkgs#164630][164630] for more information.) + + Importing the `Paths_*` module may cause builds to fail with this message: + + ``` + error: output '/nix/store/64k8iw0ryz76qpijsnl9v87fb26v28z8-my-haskell-package-1.0.0.0' is not allowed to refer to the following paths: + /nix/store/5q5s4a07gaz50h04zpfbda8xjs8wrnhg-ghc-9.6.3 + ``` + + If that happens, first disable the check for GHC references and rebuild the + derivation: + + ```nix + pkgs.haskell.lib.overrideCabal + (pkgs.haskell.lib.justStaticExecutables my-haskell-package) + (drv: { + disallowGhcReference = false; + }) + ``` + + Then use `strings` to determine which libraries are responsible: + + ``` + $ nix-build ... + $ strings result/bin/my-haskell-binary | grep /nix/store/ + ... + /nix/store/n7ciwdlg8yyxdhbrgd6yc2d8ypnwpmgq-hs-opentelemetry-sdk-0.0.3.6/bin + ... + ``` + + Finally, use `remove-references-to` to delete those store paths from the produced output: + + ```nix + pkgs.haskell.lib.overrideCabal + (pkgs.haskell.lib.justStaticExecutables my-haskell-package) + (drv: { + postInstall = '' + ${drv.postInstall or ""} + remove-references-to -t ${pkgs.haskellPackages.hs-opentelemetry-sdk} + ''; + }) + ``` + +[164630]: https://github.com/NixOS/nixpkgs/issues/164630 `enableSeparateBinOutput drv` : Install executables produced by `drv` to a separate `bin` output. This diff --git a/doc/languages-frameworks/idris2.section.md b/doc/languages-frameworks/idris2.section.md index f1f0277cc609d..3ea9b4f988f70 100644 --- a/doc/languages-frameworks/idris2.section.md +++ b/doc/languages-frameworks/idris2.section.md @@ -19,7 +19,7 @@ let lspLibPkg = idris2Packages.buildIdris { }; idrisLibraries = [ ]; }; -in lspLibPkg.library +in lspLibPkg.library { withSource = true; } ``` The above results in a derivation with the installed library results (with sourcecode). @@ -30,6 +30,7 @@ A slightly more involved example of a fully packaged executable would be the [`i # Assuming the previous example lives in `lsp-lib.nix`: let lspLib = callPackage ./lsp-lib.nix { }; + inherit (idris2Packages) idris2Api; lspPkg = idris2Packages.buildIdris { ipkgName = "idris2-lsp"; src = fetchFromGitHub { @@ -38,10 +39,9 @@ let lspLib = callPackage ./lsp-lib.nix { }; rev = "main"; hash = "sha256-vQTzEltkx7uelDtXOHc6QRWZ4cSlhhm5ziOqWA+aujk="; }; - idrisLibraries = [(idris2Packages.idris2Api { }) (lspLib { })]; + idrisLibraries = [idris2Api lspLib]; }; in lspPkg.executable ``` -The above uses the default value of `withSource = false` for both of the two required Idris libraries that the `idris2-lsp` executable depends on. `idris2Api` in the above derivation comes built in with `idris2Packages`. This library exposes many of the otherwise internal APIs of the Idris2 compiler. - +The above uses the default value of `withSource = false` for the `idris2Api` but could be modified to include that library's source by passing `(idris2Api { withSource = true; })` to `idrisLibraries` instead. `idris2Api` in the above derivation comes built in with `idris2Packages`. This library exposes many of the otherwise internal APIs of the Idris2 compiler. diff --git a/doc/languages-frameworks/index.md b/doc/languages-frameworks/index.md index 920e5e7bd431e..32cb2121620b5 100644 --- a/doc/languages-frameworks/index.md +++ b/doc/languages-frameworks/index.md @@ -2,6 +2,54 @@ 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. +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) + + For example, search for [`haskellPackages`](https://search.nixos.org/packages?query=haskellPackages) or [`rubyPackages`](https://search.nixos.org/packages?query=rubyPackages). + +- Navigate attribute sets with [`nix repl`](https://nixos.org/manual/nix/stable/command-ref/new-cli/nix3-repl). + + This technique is generally useful to inspect Nix language data structures. + + :::{.example #example-navigte-nix-repl} + + # Navigate Java compiler variants in `javaPackages` with `nix repl` + + ```shell-session + $ nix repl '<nixpkgs>' -I nixpkgs=channel:nixpkgs-unstable + nix-repl> javaPackages.<tab> + javaPackages.compiler javaPackages.openjfx15 javaPackages.openjfx21 javaPackages.recurseForDerivations + javaPackages.jogl_2_4_0 javaPackages.openjfx17 javaPackages.openjfx22 + javaPackages.mavenfod javaPackages.openjfx19 javaPackages.override + javaPackages.openjfx11 javaPackages.openjfx20 javaPackages.overrideDerivation + ``` + ::: + +- List all derivations on the command line with [`nix-env --query`](https://nixos.org/manual/nix/stable/command-ref/nix-env/query). + + `nix-env` is the only convenient way to do that, as it will skip attributes that fail [assertions](https://nixos.org/manual/nix/stable/language/constructs#assertions), such as when a package is [marked as broken](#var-meta-broken), rather than failing the entire evaluation. + + :::{.example #example-list-haskellPackages} + + # List all Python packages in Nixpkgs + + The following command lists all [derivations names](https://nixos.org/manual/nix/stable/language/derivations#attr-name) with their attribute path from the latest Nixpkgs rolling release (`nixpkgs-unstable`). + + ```shell-session + $ nix-env -qaP -f '<nixpkgs>' -A pythonPackages -I nixpkgs=channel:nixpkgs-unstable + ``` + + ```console + pythonPackages.avahi avahi-0.8 + pythonPackages.boost boost-1.81.0 + pythonPackages.caffe caffe-1.0 + pythonPackages.caffeWithCuda caffe-1.0 + pythonPackages.cbeams cbeams-1.0.3 + … + ``` + ::: + ```{=include=} sections agda.section.md android.section.md @@ -19,6 +67,7 @@ dotnet.section.md emscripten.section.md gnome.section.md go.section.md +hare.section.md haskell.section.md hy.section.md idris.section.md diff --git a/doc/languages-frameworks/javascript.section.md b/doc/languages-frameworks/javascript.section.md index f706f92c6691f..76db9d0007ce5 100644 --- a/doc/languages-frameworks/javascript.section.md +++ b/doc/languages-frameworks/javascript.section.md @@ -310,6 +310,71 @@ See `node2nix` [docs](https://github.com/svanderburg/node2nix) for more info. - `node2nix` has some [bugs](https://github.com/svanderburg/node2nix/issues/238) related to working with lock files from npm distributed with `nodejs_16`. - `node2nix` does not like missing packages from npm. If you see something like `Cannot resolve version: vue-loader-v16@undefined` then you might want to try another tool. The package might have been pulled off of npm. +### pnpm {#javascript-pnpm} + +Pnpm is available as the top-level package `pnpm`. Additionally, there are variants pinned to certain major versions, like `pnpm_8` and `pnpm_9`, which support different sets of lock file versions. + +When packaging an application that includes a `pnpm-lock.yaml`, you need to fetch the pnpm store for that project using a fixed-output-derivation. The functions `pnpm_8.fetchDeps` and `pnpm_9.fetchDeps` can create this pnpm store derivation. In conjunction, the setup hooks `pnpm_8.configHook` and `pnpm_9.configHook` will prepare the build environment to install the prefetched dependencies store. Here is an example for a package that contains a `package.json` and a `pnpm-lock.yaml` files using the above `pnpm_` attributes: + +```nix +{ + stdenv, + nodejs, + # This is pinned as { pnpm = pnpm_9; } + pnpm +}: + +stdenv.mkDerivation (finalAttrs: { + pname = "foo"; + version = "0-unstable-1980-01-01"; + + src = ...; + + nativeBuildInputs = [ + nodejs + pnpm.configHook + ]; + + pnpmDeps = pnpm.fetchDeps { + inherit (finalAttrs) pname version src; + hash = "..."; + }; +}) +``` + +NOTE: It is highly recommended to use a pinned version of pnpm (i.e. `pnpm_8` or `pnpm_9`), to increase future reproducibility. It might also be required to use an older version, if the package needs support for a certain lock file version. + +In case you are patching `package.json` or `pnpm-lock.yaml`, make sure to pass `finalAttrs.patches` to the function as well (i.e. `inherit (finalAttrs) patches`. + +#### Dealing with `sourceRoot` {#javascript-pnpm-sourceRoot} + +NOTE: Nixpkgs pnpm tooling doesn't support building projects with a `pnpm-workspace.yaml`, or building monorepos. It maybe possible to use `pnpm.fetchDeps` for these projects, but it may be hard or impossible to produce a binary from such projects ([an example attempt](https://github.com/NixOS/nixpkgs/pull/290715#issuecomment-2144543728)). + +If the pnpm project is in a subdirectory, you can just define `sourceRoot` or `setSourceRoot` for `fetchDeps`. Note, that projects using `pnpm-workspace.yaml` are currently not supported, and will probably not work using this approach. +If `sourceRoot` is different between the parent derivation and `fetchDeps`, you will have to set `pnpmRoot` to effectively be the same location as it is in `fetchDeps`. + +Assuming the following directory structure, we can define `sourceRoot` and `pnpmRoot` as follows: + +``` +. +├── frontend +│ ├── ... +│ ├── package.json +│ └── pnpm-lock.yaml +└── ... +``` + +```nix + ... + pnpmDeps = pnpm.fetchDeps { + ... + sourceRoot = "${finalAttrs.src.name}/frontend"; + }; + + # by default the working directory is the extracted source + pnpmRoot = "frontend"; +``` + ### yarn2nix {#javascript-yarn2nix} #### Preparation {#javascript-yarn2nix-preparation} diff --git a/doc/languages-frameworks/nim.section.md b/doc/languages-frameworks/nim.section.md index c6ebf49b83f66..71e3ae25a86d9 100644 --- a/doc/languages-frameworks/nim.section.md +++ b/doc/languages-frameworks/nim.section.md @@ -7,7 +7,7 @@ The following example shows a Nim program that depends only on Nim libraries: ```nix { lib, buildNimPackage, fetchFromGitHub }: -buildNimPackage { } (finalAttrs: { +buildNimPackage (finalAttrs: { pname = "ttop"; version = "1.2.7"; @@ -80,7 +80,6 @@ For example, to propagate a dependency on SDL2 for lockfiles that select the Nim /* … */ sdl2 = lockAttrs: - finalAttrs: { buildInputs ? [ ], ... }: { buildInputs = buildInputs ++ [ SDL2 ]; @@ -89,9 +88,8 @@ For example, to propagate a dependency on SDL2 for lockfiles that select the Nim } ``` -The annotations in the `nim-overrides.nix` set are functions that take three arguments and return a new attrset to be overlayed on the package being built. +The annotations in the `nim-overrides.nix` set are functions that take two arguments and return a new attrset to be overlayed on the package being built. - lockAttrs: the attrset for this library from within a lockfile. This can be used to implement library version constraints, such as marking libraries as broken or insecure. -- finalAttrs: the final attrset passed by `buildNimPackage` to `stdenv.mkDerivation`. - prevAttrs: the attrset produced by initial arguments to `buildNimPackage` and any preceding lockfile overlays. ### Overriding an Nim library override {#nim-lock-overrides-overrides} diff --git a/doc/languages-frameworks/ocaml.section.md b/doc/languages-frameworks/ocaml.section.md index 44f514e90a1b9..46fddcb3b9dee 100644 --- a/doc/languages-frameworks/ocaml.section.md +++ b/doc/languages-frameworks/ocaml.section.md @@ -120,14 +120,6 @@ buildDunePackage rec { } ``` -Note about `minimalOCamlVersion`. A deprecated version of this argument was -spelled `minimumOCamlVersion`; setting the old attribute wrongly modifies the -derivation hash and is therefore inappropriate. As a technical dept, currently -packaged libraries may still use the old spelling: maintainers are invited to -fix this when updating packages. Massive renaming is strongly discouraged as it -would be challenging to review, difficult to test, and will cause unnecessary -rebuild. - The build will automatically fail if two distinct versions of the same library are added to `buildInputs` (which usually happens transitively because of `propagatedBuildInputs`). Set `dontDetectOcamlConflicts` to true to disable this diff --git a/doc/languages-frameworks/python.section.md b/doc/languages-frameworks/python.section.md index 4c4ecf0fa278d..827c85146537d 100644 --- a/doc/languages-frameworks/python.section.md +++ b/doc/languages-frameworks/python.section.md @@ -31,8 +31,8 @@ Each interpreter has the following attributes: ### Building packages and applications {#building-packages-and-applications} -Python libraries and applications that use `setuptools` or -`distutils` are typically built with respectively the [`buildPythonPackage`](#buildpythonpackage-function) and +Python libraries and applications that use tools to follow PEP 517 (e.g. `setuptools` or `hatchling`, etc.) or +previous tools such as `distutils` are typically built with respectively the [`buildPythonPackage`](#buildpythonpackage-function) and [`buildPythonApplication`](#buildpythonapplication-function) functions. These two functions also support installing a `wheel`. All Python packages reside in `pkgs/top-level/python-packages.nix` and all @@ -78,6 +78,7 @@ The following is an example: , fetchPypi # build-system +, setuptools , setuptools-scm # dependencies @@ -107,6 +108,7 @@ buildPythonPackage rec { ''; build-system = [ + setuptools setuptools-scm ]; @@ -134,13 +136,13 @@ buildPythonPackage rec { The `buildPythonPackage` mainly does four things: -* In the [`buildPhase`](#build-phase), it calls `${python.pythonOnBuildForHost.interpreter} setup.py bdist_wheel` to +* In the [`buildPhase`](#build-phase), it calls `${python.pythonOnBuildForHost.interpreter} -m build --wheel` to build a wheel binary zipfile. -* In the [`installPhase`](#ssec-install-phase), it installs the wheel file using `pip install *.whl`. +* In the [`installPhase`](#ssec-install-phase), it installs the wheel file using `${python.pythonOnBuildForHost.interpreter} -m installer *.whl`. * In the [`postFixup`](#var-stdenv-postFixup) phase, the `wrapPythonPrograms` bash function is called to wrap all programs in the `$out/bin/*` directory to include `$PATH` environment variable and add dependent libraries to script's `sys.path`. -* In the [`installCheck`](#ssec-installCheck-phase) phase, `${python.interpreter} setup.py test` is run. +* In the [`installCheck`](#ssec-installCheck-phase) phase, `${python.interpreter} -m pytest` is run. By default tests are run because [`doCheck = true`](#var-stdenv-doCheck). Test dependencies, like e.g. the test runner, should be added to [`nativeCheckInputs`](#var-stdenv-nativeCheckInputs). @@ -177,10 +179,6 @@ following are specific to `buildPythonPackage`: `makeWrapperArgs = ["--set FOO BAR" "--set BAZ QUX"]`. * `namePrefix`: Prepends text to `${name}` parameter. In case of libraries, this defaults to `"python3.8-"` for Python 3.8, etc., and in case of applications to `""`. -* `pipInstallFlags ? []`: A list of strings. Arguments to be passed to `pip - install`. To pass options to `python setup.py install`, use - `--install-option`. E.g., `pipInstallFlags=["--install-option='--cpp_implementation'"]`. -* `pipBuildFlags ? []`: A list of strings. Arguments to be passed to `pip wheel`. * `pypaBuildFlags ? []`: A list of strings. Arguments to be passed to `python -m build --wheel`. * `pythonPath ? []`: List of packages to be added into `$PYTHONPATH`. Packages in `pythonPath` are not propagated (contrary to [`propagatedBuildInputs`](#var-stdenv-propagatedBuildInputs)). @@ -298,7 +296,6 @@ python3Packages.buildPythonApplication rec { build-system = with python3Packages; [ setuptools - wheel ]; dependencies = with python3Packages; [ @@ -465,13 +462,11 @@ are used in [`buildPythonPackage`](#buildpythonpackage-function). with the `eggInstallHook` - `eggBuildHook` to skip building for eggs. - `eggInstallHook` to install eggs. -- `pipBuildHook` to build a wheel using `pip` and PEP 517. Note a build system - (e.g. `setuptools` or `flit`) should still be added as `build-system`. - `pypaBuildHook` to build a wheel using [`pypa/build`](https://pypa-build.readthedocs.io/en/latest/index.html) and PEP 517/518. Note a build system (e.g. `setuptools` or `flit`) should still be added as `build-system`. -- `pipInstallHook` to install wheels. +- `pypaInstallHook` to install wheels. - `pytestCheckHook` to run tests with `pytest`. See [example usage](#using-pytestcheckhook). - `pythonCatchConflictsHook` to fail if the package depends on two different versions of the same dependency. - `pythonImportsCheckHook` to check whether importing the listed modules works. @@ -609,7 +604,8 @@ that sets up an interpreter pointing to them. This matters much more for "big" modules like `pytorch` or `tensorflow`. Module names usually match their names on [pypi.org](https://pypi.org/), but -you can use the [Nixpkgs search website](https://nixos.org/nixos/packages.html) +normalized according to PEP 503/508. (e.g. Foo__Bar.baz -> foo-bar-baz) +You can use the [Nixpkgs search website](https://nixos.org/nixos/packages.html) to find them as well (along with non-python packages). At this point we can create throwaway experimental Python environments with @@ -837,7 +833,6 @@ building Python libraries is [`buildPythonPackage`](#buildpythonpackage-function , buildPythonPackage , fetchPypi , setuptools -, wheel }: buildPythonPackage rec { @@ -852,7 +847,6 @@ buildPythonPackage rec { build-system = [ setuptools - wheel ]; # has no tests @@ -876,7 +870,7 @@ buildPythonPackage rec { What happens here? The function [`buildPythonPackage`](#buildpythonpackage-function) is called and as argument it accepts a set. In this case the set is a recursive set, `rec`. One of the arguments is the name of the package, which consists of a basename (generally -following the name on PyPi) and a version. Another argument, `src` specifies the +following the name on PyPI) and a version. Another argument, `src` specifies the source, which in this case is fetched from PyPI using the helper function `fetchPypi`. The argument `doCheck` is used to set whether tests should be run when building the package. Since there are no tests, we rely on [`pythonImportsCheck`](#using-pythonimportscheck) @@ -911,7 +905,6 @@ with import <nixpkgs> {}; build-system = [ python311.pkgs.setuptools - python311.pkgs.wheel ]; # has no tests @@ -964,13 +957,13 @@ order to build [`datashape`](https://github.com/blaze/datashape). , fetchPypi # build dependencies -, setuptools, wheel +, setuptools # dependencies , numpy, multipledispatch, python-dateutil # tests -, pytest +, pytestCheckHook }: buildPythonPackage rec { @@ -985,7 +978,6 @@ buildPythonPackage rec { build-system = [ setuptools - wheel ]; dependencies = [ @@ -995,7 +987,7 @@ buildPythonPackage rec { ]; nativeCheckInputs = [ - pytest + pytestCheckHook ]; meta = { @@ -1008,8 +1000,8 @@ buildPythonPackage rec { ``` We can see several runtime dependencies, `numpy`, `multipledispatch`, and -`python-dateutil`. Furthermore, we have [`nativeCheckInputs`](#var-stdenv-nativeCheckInputs) with `pytest`. -`pytest` is a test runner and is only used during the [`checkPhase`](#ssec-check-phase) and is +`python-dateutil`. Furthermore, we have [`nativeCheckInputs`](#var-stdenv-nativeCheckInputs) with `pytestCheckHook`. +`pytestCheckHook` is a test runner hook and is only used during the [`checkPhase`](#ssec-check-phase) and is therefore not added to `dependencies`. In the previous case we had only dependencies on other Python packages to consider. @@ -1022,7 +1014,6 @@ when building the bindings and are therefore added as [`buildInputs`](#var-stden , buildPythonPackage , fetchPypi , setuptools -, wheel , libxml2 , libxslt }: @@ -1039,7 +1030,6 @@ buildPythonPackage rec { build-system = [ setuptools - wheel ]; buildInputs = [ @@ -1047,6 +1037,14 @@ buildPythonPackage rec { libxslt ]; + # tests are meant to be ran "in-place" in the same directory as src + doCheck = false; + + pythonImportsCheck = [ + "lxml" + "lxml.etree" + ]; + meta = { changelog = "https://github.com/lxml/lxml/releases/tag/lxml-${version}"; description = "Pythonic binding for the libxml2 and libxslt libraries"; @@ -1074,7 +1072,6 @@ therefore we have to set `LDFLAGS` and `CFLAGS`. # build dependencies , setuptools -, wheel # dependencies , fftw @@ -1085,7 +1082,7 @@ therefore we have to set `LDFLAGS` and `CFLAGS`. }: buildPythonPackage rec { - pname = "pyFFTW"; + pname = "pyfftw"; version = "0.9.2"; pyproject = true; @@ -1096,7 +1093,6 @@ buildPythonPackage rec { build-system = [ setuptools - wheel ]; buildInputs = [ @@ -1118,6 +1114,8 @@ buildPythonPackage rec { # Tests cannot import pyfftw. pyfftw works fine though. doCheck = false; + pythonImportsCheck = [ "pyfftw" ]; + meta = { changelog = "https://github.com/pyFFTW/pyFFTW/releases/tag/v${version}"; description = "A pythonic wrapper around FFTW, the FFT library, presenting a unified interface for all the supported transforms"; @@ -1133,10 +1131,8 @@ Note also the line [`doCheck = false;`](#var-stdenv-doCheck), we explicitly disa It is highly encouraged to have testing as part of the package build. This helps to avoid situations where the package was able to build and install, -but is not usable at runtime. Currently, all packages will use the `test` -command provided by the setup.py (i.e. `python setup.py test`). However, -this is currently deprecated https://github.com/pypa/setuptools/pull/1878 -and your package should provide its own [`checkPhase`](#ssec-check-phase). +but is not usable at runtime. +Your package should provide its own [`checkPhase`](#ssec-check-phase). ::: {.note} The [`checkPhase`](#ssec-check-phase) for python maps to the `installCheckPhase` on a @@ -1207,9 +1203,11 @@ been removed, in this case, it's recommended to use `pytestCheckHook`. #### Using pytestCheckHook {#using-pytestcheckhook} -`pytestCheckHook` is a convenient hook which will substitute the setuptools -`test` command for a [`checkPhase`](#ssec-check-phase) which runs `pytest`. This is also beneficial +`pytestCheckHook` is a convenient hook which will set up (or configure) +a [`checkPhase`](#ssec-check-phase) to run `pytest`. This is also beneficial when a package may need many items disabled to run the test suite. +Most packages use `pytest` or `unittest`, which is compatible with `pytest`, +so you will most likely use `pytestCheckHook`. Using the example above, the analogous `pytestCheckHook` usage would be: @@ -1364,10 +1362,12 @@ instead of a dev dependency). Keep in mind that while the examples above are done with `requirements.txt`, `pythonRelaxDepsHook` works by modifying the resulting wheel file, so it should work with any of the [existing hooks](#setup-hooks). +It indicates that `pythonRelaxDepsHook` has no effect on build time dependencies, such as in `build-system`. +If a package requires incompatible build time dependencies, they should be removed in `postPatch` with `substituteInPlace` or something similar. #### Using unittestCheckHook {#using-unittestcheckhook} -`unittestCheckHook` is a hook which will substitute the setuptools `test` command for a [`checkPhase`](#ssec-check-phase) which runs `python -m unittest discover`: +`unittestCheckHook` is a hook which will set up (or configure) a [`checkPhase`](#ssec-check-phase) to run `python -m unittest discover`: ```nix { @@ -1381,6 +1381,8 @@ work with any of the [existing hooks](#setup-hooks). } ``` +`pytest` is compatible with `unittest`, so in most cases you can use `pytestCheckHook` instead. + #### Using sphinxHook {#using-sphinxhook} The `sphinxHook` is a helpful tool to build documentation and manpages @@ -1459,7 +1461,6 @@ We first create a function that builds `toolz` in `~/path/to/toolz/release.nix` , buildPythonPackage , fetchPypi , setuptools -, wheel }: buildPythonPackage rec { @@ -1474,7 +1475,6 @@ buildPythonPackage rec { build-system = [ setuptools - wheel ]; meta = { @@ -1494,10 +1494,9 @@ with import <nixpkgs> {}; ( let toolz = callPackage /path/to/toolz/release.nix { - buildPythonPackage = python310 -Packages.buildPythonPackage; + buildPythonPackage = python3Packages.buildPythonPackage; }; - in python310.withPackages (ps: [ + in python3.withPackages (ps: [ ps.numpy toolz ]) @@ -1918,6 +1917,8 @@ because we can only provide security support for non-vendored dependencies. We recommend [nix-init](https://github.com/nix-community/nix-init) for creating new python packages within nixpkgs, as it already prefetches the source, parses dependencies for common formats and prefills most things in `meta`. +See also [contributing section](#contributing). + ### Are Python interpreters built deterministically? {#deterministic-builds} The Python interpreters are now built deterministically. Minor modifications had @@ -1935,16 +1936,15 @@ Both are also exported in `nix-shell`. It is recommended to test packages as part of the build process. Source distributions (`sdist`) often include test files, but not always. -By default the command `python setup.py test` is run as part of the -[`checkPhase`](#ssec-check-phase), but often it is necessary to pass a custom [`checkPhase`](#ssec-check-phase). An -example of such a situation is when `py.test` is used. +The best practice today is to pass a test hook (e.g. pytestCheckHook, unittestCheckHook) into nativeCheckInputs. +This will reconfigure the checkPhase to make use of that particular test framework. +Occasionally packages don't make use of a common test framework, which may then require a custom checkPhase. #### Common issues {#common-issues} -* Non-working tests can often be deselected. By default [`buildPythonPackage`](#buildpythonpackage-function) - runs `python setup.py test`. which is deprecated. Most Python modules however - do follow the standard test protocol where the pytest runner can be used - instead. `pytest` supports the `-k` and `--ignore` parameters to ignore test +* Non-working tests can often be deselected. Most Python modules + do follow the standard test protocol where the pytest runner can be used. + `pytest` supports the `-k` and `--ignore` parameters to ignore test methods or classes as well as whole files. For `pytestCheckHook` these are conveniently exposed as `disabledTests` and `disabledTestPaths` respectively. @@ -1985,14 +1985,25 @@ The following rules are desired to be respected: * Python applications live outside of `python-packages.nix` and are packaged with [`buildPythonApplication`](#buildpythonapplication-function). * Make sure libraries build for all Python interpreters. -* By default we enable tests. Make sure the tests are found and, in the case of + If it fails to build on some Python versions, consider disabling them by setting `disable = pythonAtLeast "3.x"` along with a comment. +* The two parameters, `pyproject` and `build-system` are set to avoid the legacy setuptools/distutils build. +* Only unversioned attributes (e.g. `pydantic`, but not `pypdantic_1`) can be included in `dependencies`, + since due to `PYTHONPATH` limitations we can only ever support a single version for libraries + without running into duplicate module name conflicts. +* The version restrictions of `dependencies` can be relaxed by [`pythonRelaxDepsHook`](#using-pythonrelaxdepshook). +* Make sure the tests are enabled using for example [`pytestCheckHook`](#using-pytestcheckhook) and, in the case of libraries, are passing for all interpreters. If certain tests fail they can be disabled individually. Try to avoid disabling the tests altogether. In any case, when you disable tests, leave a comment explaining why. +* `pythonImportsCheck` is set. This is still a good smoke test even if `pytestCheckHook` is set. +* `meta.platforms` takes the default value in many cases. + It does not need to be set explicitly unless the package requires a specific platform. +* The file is formatted with `nixfmt-rfc-style`. * Commit names of Python libraries should reflect that they are Python libraries, so write for example `python311Packages.numpy: 1.11 -> 1.12`. It is highly recommended to specify the current default version to enable automatic build by ofborg. + Note that `pythonPackages` is an alias for `python27Packages`. * Attribute names in `python-packages.nix` as well as `pname`s should match the library's name on PyPI, but be normalized according to [PEP 0503](https://www.python.org/dev/peps/pep-0503/#normalized-names). This means @@ -2006,6 +2017,8 @@ The following rules are desired to be respected: * Attribute names in `python-packages.nix` should be sorted alphanumerically to avoid merge conflicts and ease locating attributes. +This list is useful for reviewers as well as for self-checking when submitting packages. + ## Package set maintenance {#python-package-set-maintenance} The whole Python package set has a lot of packages that do not see regular diff --git a/doc/languages-frameworks/rust.section.md b/doc/languages-frameworks/rust.section.md index 8a1007b7bb8a9..e12bbe02bfb52 100644 --- a/doc/languages-frameworks/rust.section.md +++ b/doc/languages-frameworks/rust.section.md @@ -254,7 +254,7 @@ By default, it takes the `stdenv.hostPlatform.config` and replaces components where they are known to differ. But there are ways to customize the argument: - To choose a different target by name, define - `stdenv.hostPlatform.rustc.config` as that name (a string), and that + `stdenv.hostPlatform.rust.rustcTarget` as that name (a string), and that name will be used instead. For example: @@ -262,7 +262,7 @@ where they are known to differ. But there are ways to customize the argument: ```nix import <nixpkgs> { crossSystem = (import <nixpkgs/lib>).systems.examples.armhf-embedded // { - rustc.config = "thumbv7em-none-eabi"; + rust.rustcTarget = "thumbv7em-none-eabi"; }; } ``` @@ -274,10 +274,10 @@ where they are known to differ. But there are ways to customize the argument: ``` - To pass a completely custom target, define - `stdenv.hostPlatform.rustc.config` with its name, and - `stdenv.hostPlatform.rustc.platform` with the value. The value will be + `stdenv.hostPlatform.rust.rustcTarget` with its name, and + `stdenv.hostPlatform.rust.platform` with the value. The value will be serialized to JSON in a file called - `${stdenv.hostPlatform.rustc.config}.json`, and the path of that file + `${stdenv.hostPlatform.rust.rustcTarget}.json`, and the path of that file will be used instead. For example: @@ -285,8 +285,8 @@ where they are known to differ. But there are ways to customize the argument: ```nix import <nixpkgs> { crossSystem = (import <nixpkgs/lib>).systems.examples.armhf-embedded // { - rustc.config = "thumb-crazy"; - rustc.platform = { foo = ""; bar = ""; }; + rust.rustcTarget = "thumb-crazy"; + rust.platform = { foo = ""; bar = ""; }; }; } ``` diff --git a/doc/languages-frameworks/vim.section.md b/doc/languages-frameworks/vim.section.md index 69031ccbd3406..ea10d50455830 100644 --- a/doc/languages-frameworks/vim.section.md +++ b/doc/languages-frameworks/vim.section.md @@ -214,7 +214,7 @@ Note: this is not possible anymore for Neovim. Nix expressions for Vim plugins are stored in [pkgs/applications/editors/vim/plugins](https://github.com/NixOS/nixpkgs/tree/master/pkgs/applications/editors/vim/plugins). For the vast majority of plugins, Nix expressions are automatically generated by running [`nix-shell -p vimPluginsUpdater --run vim-plugins-updater`](https://github.com/NixOS/nixpkgs/blob/master/pkgs/applications/editors/vim/plugins/updater.nix). This creates a [generated.nix](https://github.com/NixOS/nixpkgs/blob/master/pkgs/applications/editors/vim/plugins/generated.nix) file based on the plugins listed in [vim-plugin-names](https://github.com/NixOS/nixpkgs/blob/master/pkgs/applications/editors/vim/plugins/vim-plugin-names). -After running the updater, if nvim-treesitter received an update, also run [`nvim-treesitter/update.py`](https://github.com/NixOS/nixpkgs/blob/master/pkgs/applications/editors/vim/plugins/update.py) to update the tree sitter grammars for `nvim-treesitter`. +When the vim updater detects an nvim-treesitter update, it also runs [`nvim-treesitter/update.py $(nix-build -A vimPlugins.nvim-treesitter)`](https://github.com/NixOS/nixpkgs/blob/master/pkgs/applications/editors/vim/plugins/update.py) to update the tree sitter grammars for `nvim-treesitter`. Some plugins require overrides in order to function properly. Overrides are placed in [overrides.nix](https://github.com/NixOS/nixpkgs/blob/master/pkgs/applications/editors/vim/plugins/overrides.nix). Overrides are most often required when a plugin requires some dependencies, or extra steps are required during the build process. For example `deoplete-fish` requires both `deoplete-nvim` and `vim-fish`, and so the following override was added: |