commit 1e1cd398d44942f054531ac806ff370a09129c1a · pyrox.dev/nixpkgs

+205

CONTRIBUTING-new.md

···

       160
       160
        
         and security fixes with a big impact on Hydra builds should be

     

       161
       161
        
         contributed to this branch. This branch is merged into master when

     

       162
       162
        
         deemed of sufficiently high quality

     

       163
       163
       +
       

     

       164
       164
       +
       ## Coding conventions {#chap-conventions}

     

       165
       165
       +
       

     

       166
       166
       +
       ### File naming and organisation {#sec-organisation}

     

       167
       167
       +
       

     

       168
       168
       +
       Names of files and directories should be in lowercase, with dashes between words — not in camel case. For instance, it should be `all-packages.nix`, not `allPackages.nix` or `AllPackages.nix`.

     

       169
       169
       +
       

     

       170
       170
       +
       ### Syntax {#sec-syntax}

     

       171
       171
       +
       

     

       172
       172
       +
       - Use 2 spaces of indentation per indentation level in Nix expressions, 4 spaces in shell scripts.

     

       173
       173
       +
       

     

       174
       174
       +
       - Do not use tab characters, i.e. configure your editor to use soft tabs. For instance, use `(setq-default indent-tabs-mode nil)` in Emacs. Everybody has different tab settings so it’s asking for trouble.

     

       175
       175
       +
       

     

       176
       176
       +
       - Use `lowerCamelCase` for variable names, not `UpperCamelCase`. Note, this rule does not apply to package attribute names, which instead follow the rules in [](#sec-package-naming).

     

       177
       177
       +
       

     

       178
       178
       +
       - Function calls with attribute set arguments are written as

     

       179
       179
       +
       

     

       180
       180
       +
         ```nix

     

       181
       181
       +
         foo {

     

       182
       182
       +
           arg = ...;

     

       183
       183
       +
         }

     

       184
       184
       +
         ```

     

       185
       185
       +
       

     

       186
       186
       +
         not

     

       187
       187
       +
       

     

       188
       188
       +
         ```nix

     

       189
       189
       +
         foo

     

       190
       190
       +
         {

     

       191
       191
       +
           arg = ...;

     

       192
       192
       +
         }

     

       193
       193
       +
         ```

     

       194
       194
       +
       

     

       195
       195
       +
         Also fine is

     

       196
       196
       +
       

     

       197
       197
       +
         ```nix

     

       198
       198
       +
         foo { arg = ...; }

     

       199
       199
       +
         ```

     

       200
       200
       +
       

     

       201
       201
       +
         if it's a short call.

     

       202
       202
       +
       

     

       203
       203
       +
       - In attribute sets or lists that span multiple lines, the attribute names or list elements should be aligned:

     

       204
       204
       +
       

     

       205
       205
       +
         ```nix

     

       206
       206
       +
         # A long list.

     

       207
       207
       +
         list = [

     

       208
       208
       +
           elem1

     

       209
       209
       +
           elem2

     

       210
       210
       +
           elem3

     

       211
       211
       +
         ];

     

       212
       212
       +
       

     

       213
       213
       +
         # A long attribute set.

     

       214
       214
       +
         attrs = {

     

       215
       215
       +
           attr1 = short_expr;

     

       216
       216
       +
           attr2 =

     

       217
       217
       +
             if true then big_expr else big_expr;

     

       218
       218
       +
         };

     

       219
       219
       +
       

     

       220
       220
       +
         # Combined

     

       221
       221
       +
         listOfAttrs = [

     

       222
       222
       +
           {

     

       223
       223
       +
             attr1 = 3;

     

       224
       224
       +
             attr2 = "fff";

     

       225
       225
       +
           }

     

       226
       226
       +
           {

     

       227
       227
       +
             attr1 = 5;

     

       228
       228
       +
             attr2 = "ggg";

     

       229
       229
       +
           }

     

       230
       230
       +
         ];

     

       231
       231
       +
         ```

     

       232
       232
       +
       

     

       233
       233
       +
       - Short lists or attribute sets can be written on one line:

     

       234
       234
       +
       

     

       235
       235
       +
         ```nix

     

       236
       236
       +
         # A short list.

     

       237
       237
       +
         list = [ elem1 elem2 elem3 ];

     

       238
       238
       +
       

     

       239
       239
       +
         # A short set.

     

       240
       240
       +
         attrs = { x = 1280; y = 1024; };

     

       241
       241
       +
         ```

     

       242
       242
       +
       

     

       243
       243
       +
       - Breaking in the middle of a function argument can give hard-to-read code, like

     

       244
       244
       +
       

     

       245
       245
       +
         ```nix

     

       246
       246
       +
         someFunction { x = 1280;

     

       247
       247
       +
           y = 1024; } otherArg

     

       248
       248
       +
           yetAnotherArg

     

       249
       249
       +
         ```

     

       250
       250
       +
       

     

       251
       251
       +
         (especially if the argument is very large, spanning multiple lines).

     

       252
       252
       +
       

     

       253
       253
       +
         Better:

     

       254
       254
       +
       

     

       255
       255
       +
         ```nix

     

       256
       256
       +
         someFunction

     

       257
       257
       +
           { x = 1280; y = 1024; }

     

       258
       258
       +
           otherArg

     

       259
       259
       +
           yetAnotherArg

     

       260
       260
       +
         ```

     

       261
       261
       +
       

     

       262
       262
       +
         or

     

       263
       263
       +
       

     

       264
       264
       +
         ```nix

     

       265
       265
       +
         let res = { x = 1280; y = 1024; };

     

       266
       266
       +
         in someFunction res otherArg yetAnotherArg

     

       267
       267
       +
         ```

     

       268
       268
       +
       

     

       269
       269
       +
       - The bodies of functions, asserts, and withs are not indented to prevent a lot of superfluous indentation levels, i.e.

     

       270
       270
       +
       

     

       271
       271
       +
         ```nix

     

       272
       272
       +
         { arg1, arg2 }:

     

       273
       273
       +
         assert system == "i686-linux";

     

       274
       274
       +
         stdenv.mkDerivation { ...

     

       275
       275
       +
         ```

     

       276
       276
       +
       

     

       277
       277
       +
         not

     

       278
       278
       +
       

     

       279
       279
       +
         ```nix

     

       280
       280
       +
         { arg1, arg2 }:

     

       281
       281
       +
           assert system == "i686-linux";

     

       282
       282
       +
             stdenv.mkDerivation { ...

     

       283
       283
       +
         ```

     

       284
       284
       +
       

     

       285
       285
       +
       - Function formal arguments are written as:

     

       286
       286
       +
       

     

       287
       287
       +
         ```nix

     

       288
       288
       +
         { arg1, arg2, arg3 }:

     

       289
       289
       +
         ```

     

       290
       290
       +
       

     

       291
       291
       +
         but if they don't fit on one line they're written as:

     

       292
       292
       +
       

     

       293
       293
       +
         ```nix

     

       294
       294
       +
         { arg1, arg2, arg3

     

       295
       295
       +
         , arg4, ...

     

       296
       296
       +
         , # Some comment...

     

       297
       297
       +
           argN

     

       298
       298
       +
         }:

     

       299
       299
       +
         ```

     

       300
       300
       +
       

     

       301
       301
       +
       - Functions should list their expected arguments as precisely as possible. That is, write

     

       302
       302
       +
       

     

       303
       303
       +
         ```nix

     

       304
       304
       +
         { stdenv, fetchurl, perl }: ...

     

       305
       305
       +
         ```

     

       306
       306
       +
       

     

       307
       307
       +
         instead of

     

       308
       308
       +
       

     

       309
       309
       +
         ```nix

     

       310
       310
       +
         args: with args; ...

     

       311
       311
       +
         ```

     

       312
       312
       +
       

     

       313
       313
       +
         or

     

       314
       314
       +
       

     

       315
       315
       +
         ```nix

     

       316
       316
       +
         { stdenv, fetchurl, perl, ... }: ...

     

       317
       317
       +
         ```

     

       318
       318
       +
       

     

       319
       319
       +
         For functions that are truly generic in the number of arguments (such as wrappers around `mkDerivation`) that have some required arguments, you should write them using an `@`-pattern:

     

       320
       320
       +
       

     

       321
       321
       +
         ```nix

     

       322
       322
       +
         { stdenv, doCoverageAnalysis ? false, ... } @ args:

     

       323
       323
       +
       

     

       324
       324
       +
         stdenv.mkDerivation (args // {

     

       325
       325
       +
           ... if doCoverageAnalysis then "bla" else "" ...

     

       326
       326
       +
         })

     

       327
       327
       +
         ```

     

       328
       328
       +
       

     

       329
       329
       +
         instead of

     

       330
       330
       +
       

     

       331
       331
       +
         ```nix

     

       332
       332
       +
         args:

     

       333
       333
       +
       

     

       334
       334
       +
         args.stdenv.mkDerivation (args // {

     

       335
       335
       +
           ... if args ? doCoverageAnalysis && args.doCoverageAnalysis then "bla" else "" ...

     

       336
       336
       +
         })

     

       337
       337
       +
         ```

     

       338
       338
       +
       

     

       339
       339
       +
       - Unnecessary string conversions should be avoided. Do

     

       340
       340
       +
       

     

       341
       341
       +
         ```nix

     

       342
       342
       +
         rev = version;

     

       343
       343
       +
         ```

     

       344
       344
       +
       

     

       345
       345
       +
         instead of

     

       346
       346
       +
       

     

       347
       347
       +
         ```nix

     

       348
       348
       +
         rev = "${version}";

     

       349
       349
       +
         ```

     

       350
       350
       +
       

     

       351
       351
       +
       - Building lists conditionally _should_ be done with `lib.optional(s)` instead of using `if cond then [ ... ] else null` or `if cond then [ ... ] else [ ]`.

     

       352
       352
       +
       

     

       353
       353
       +
         ```nix

     

       354
       354
       +
         buildInputs = lib.optional stdenv.isDarwin iconv;

     

       355
       355
       +
         ```

     

       356
       356
       +
       

     

       357
       357
       +
         instead of

     

       358
       358
       +
       

     

       359
       359
       +
         ```nix

     

       360
       360
       +
         buildInputs = if stdenv.isDarwin then [ iconv ] else null;

     

       361
       361
       +
         ```

     

       362
       362
       +
       

     

       363
       363
       +
         As an exception, an explicit conditional expression with null can be used when fixing a important bug without triggering a mass rebuild.

     

       364
       364
       +
         If this is done a follow up pull request _should_ be created to change the code to `lib.optional(s)`.

     

       365
       365
       +
       

     

       366
       366
       +
       - Arguments should be listed in the order they are used, with the exception of `lib`, which always goes first.

     

       367
       367
       +

+17 -647

doc/contributing/coding-conventions.chapter.md

···

       1
       1
        
       # Coding conventions {#chap-conventions}

     

       2
       2
        
       

     

       3
       3
       -
       ## Syntax {#sec-syntax}

     

       4
       4
       -
       

     

       5
       5
       -
       - Use 2 spaces of indentation per indentation level in Nix expressions, 4 spaces in shell scripts.

     

       6
       6
       -
       

     

       7
       7
       -
       - Do not use tab characters, i.e. configure your editor to use soft tabs. For instance, use `(setq-default indent-tabs-mode nil)` in Emacs. Everybody has different tab settings so it’s asking for trouble.

     

       8
       8
       -
       

     

       9
       9
       -
       - Use `lowerCamelCase` for variable names, not `UpperCamelCase`. Note, this rule does not apply to package attribute names, which instead follow the rules in [](#sec-package-naming).

     

       10
       10
       -
       

     

       11
       11
       -
       - Function calls with attribute set arguments are written as

     

       12
       12
       -
       

     

       13
       13
       -
         ```nix

     

       14
       14
       -
         foo {

     

       15
       15
       -
           arg = ...;

     

       16
       16
       -
         }

     

       17
       17
       -
         ```

     

       18
       18
       -
       

     

       19
       19
       -
         not

     

       20
       20
       -
       

     

       21
       21
       -
         ```nix

     

       22
       22
       -
         foo

     

       23
       23
       -
         {

     

       24
       24
       -
           arg = ...;

     

       25
       25
       -
         }

     

       26
       26
       -
         ```

     

       27
       27
       -
       

     

       28
       28
       -
         Also fine is

     

       29
       29
       -
       

     

       30
       30
       -
         ```nix

     

       31
       31
       -
         foo { arg = ...; }

     

       32
       32
       -
         ```

     

       33
       33
       -
       

     

       34
       34
       -
         if it's a short call.

     

       35
       35
       -
       

     

       36
       36
       -
       - In attribute sets or lists that span multiple lines, the attribute names or list elements should be aligned:

     

       37
       37
       -
       

     

       38
       38
       -
         ```nix

     

       39
       39
       -
         # A long list.

     

       40
       40
       -
         list = [

     

       41
       41
       -
           elem1

     

       42
       42
       -
           elem2

     

       43
       43
       -
           elem3

     

       44
       44
       -
         ];

     

       45
       45
       -
       

     

       46
       46
       -
         # A long attribute set.

     

       47
       47
       -
         attrs = {

     

       48
       48
       -
           attr1 = short_expr;

     

       49
       49
       -
           attr2 =

     

       50
       50
       -
             if true then big_expr else big_expr;

     

       51
       51
       -
         };

     

       52
       52
       -
       

     

       53
       53
       -
         # Combined

     

       54
       54
       -
         listOfAttrs = [

     

       55
       55
       -
           {

     

       56
       56
       -
             attr1 = 3;

     

       57
       57
       -
             attr2 = "fff";

     

       58
       58
       -
           }

     

       59
       59
       -
           {

     

       60
       60
       -
             attr1 = 5;

     

       61
       61
       -
             attr2 = "ggg";

     

       62
       62
       -
           }

     

       63
       63
       -
         ];

     

       64
       64
       -
         ```

     

       65
       65
       -
       

     

       66
       66
       -
       - Short lists or attribute sets can be written on one line:

     

       67
       67
       -
       

     

       68
       68
       -
         ```nix

     

       69
       69
       -
         # A short list.

     

       70
       70
       -
         list = [ elem1 elem2 elem3 ];

     

       71
       71
       -
       

     

       72
       72
       -
         # A short set.

     

       73
       73
       -
         attrs = { x = 1280; y = 1024; };

     

       74
       74
       -
         ```

     

       75
       75
       -
       

     

       76
       76
       -
       - Breaking in the middle of a function argument can give hard-to-read code, like

     

       77
       77
       -
       

     

       78
       78
       -
         ```nix

     

       79
       79
       -
         someFunction { x = 1280;

     

       80
       80
       -
           y = 1024; } otherArg

     

       81
       81
       -
           yetAnotherArg

     

       82
       82
       -
         ```

     

       83
       83
       -
       

     

       84
       84
       -
         (especially if the argument is very large, spanning multiple lines).

     

       85
       85
       -
       

     

       86
       86
       -
         Better:

     

       87
       87
       -
       

     

       88
       88
       -
         ```nix

     

       89
       89
       -
         someFunction

     

       90
       90
       -
           { x = 1280; y = 1024; }

     

       91
       91
       -
           otherArg

     

       92
       92
       -
           yetAnotherArg

     

       93
       93
       -
         ```

     

       94
       94
       -
       

     

       95
       95
       -
         or

     

       96
       96
       -
       

     

       97
       97
       -
         ```nix

     

       98
       98
       -
         let res = { x = 1280; y = 1024; };

     

       99
       99
       -
         in someFunction res otherArg yetAnotherArg

     

       100
       100
       -
         ```

     

       101
       101
       -
       

     

       102
       102
       -
       - The bodies of functions, asserts, and withs are not indented to prevent a lot of superfluous indentation levels, i.e.

     

       103
       103
       -
       

     

       104
       104
       -
         ```nix

     

       105
       105
       -
         { arg1, arg2 }:

     

       106
       106
       -
         assert system == "i686-linux";

     

       107
       107
       -
         stdenv.mkDerivation { ...

     

       108
       108
       -
         ```

     

       109
       109
       -
       

     

       110
       110
       -
         not

     

       111
       111
       -
       

     

       112
       112
       -
         ```nix

     

       113
       113
       -
         { arg1, arg2 }:

     

       114
       114
       -
           assert system == "i686-linux";

     

       115
       115
       -
             stdenv.mkDerivation { ...

     

       116
       116
       -
         ```

     

       117
       117
       -
       

     

       118
       118
       -
       - Function formal arguments are written as:

     

       119
       119
       -
       

     

       120
       120
       -
         ```nix

     

       121
       121
       -
         { arg1, arg2, arg3 }:

     

       122
       122
       -
         ```

     

       123
       123
       -
       

     

       124
       124
       -
         but if they don't fit on one line they're written as:

     

       125
       125
       -
       

     

       126
       126
       -
         ```nix

     

       127
       127
       -
         { arg1, arg2, arg3

     

       128
       128
       -
         , arg4, ...

     

       129
       129
       -
         , # Some comment...

     

       130
       130
       -
           argN

     

       131
       131
       -
         }:

     

       132
       132
       -
         ```

     

       133
       133
       -
       

     

       134
       134
       -
       - Functions should list their expected arguments as precisely as possible. That is, write

     

       135
       135
       -
       

     

       136
       136
       -
         ```nix

     

       137
       137
       -
         { stdenv, fetchurl, perl }: ...

     

       138
       138
       -
         ```

     

       139
       139
       -
       

     

       140
       140
       -
         instead of

     

       141
       141
       -
       

     

       142
       142
       -
         ```nix

     

       143
       143
       -
         args: with args; ...

     

       144
       144
       -
         ```

     

       145
       145
       -
       

     

       146
       146
       -
         or

     

       147
       147
       -
       

     

       148
       148
       -
         ```nix

     

       149
       149
       -
         { stdenv, fetchurl, perl, ... }: ...

     

       150
       150
       -
         ```

     

       151
       151
       -
       

     

       152
       152
       -
         For functions that are truly generic in the number of arguments (such as wrappers around `mkDerivation`) that have some required arguments, you should write them using an `@`-pattern:

     

       153
       153
       -
       

     

       154
       154
       -
         ```nix

     

       155
       155
       -
         { stdenv, doCoverageAnalysis ? false, ... } @ args:

     

       156
       156
       -
       

     

       157
       157
       -
         stdenv.mkDerivation (args // {

     

       158
       158
       -
           ... if doCoverageAnalysis then "bla" else "" ...

     

       159
       159
       -
         })

     

       160
       160
       -
         ```

     

       161
       161
       -
       

     

       162
       162
       -
         instead of

     

       163
       163
       -
       

     

       164
       164
       -
         ```nix

     

       165
       165
       -
         args:

     

       166
       166
       -
       

     

       167
       167
       -
         args.stdenv.mkDerivation (args // {

     

       168
       168
       -
           ... if args ? doCoverageAnalysis && args.doCoverageAnalysis then "bla" else "" ...

     

       169
       169
       -
         })

     

       170
       170
       -
         ```

     

       171
       171
       -
       

     

       172
       172
       -
       - Unnecessary string conversions should be avoided. Do

     

       173
       173
       -
       

     

       174
       174
       -
         ```nix

     

       175
       175
       -
         rev = version;

     

       176
       176
       -
         ```

     

       177
       177
       -
       

     

       178
       178
       -
         instead of

     

       179
       179
       -
       

     

       180
       180
       -
         ```nix

     

       181
       181
       -
         rev = "${version}";

     

       182
       182
       -
         ```

     

       183
       183
       -
       

     

       184
       184
       -
       - Building lists conditionally _should_ be done with `lib.optional(s)` instead of using `if cond then [ ... ] else null` or `if cond then [ ... ] else [ ]`.

     

       185
       185
       -
       

     

       186
       186
       -
         ```nix

     

       187
       187
       -
         buildInputs = lib.optional stdenv.isDarwin iconv;

     

       188
       188
       -
         ```

     

       189
       189
       -
       

     

       190
       190
       -
         instead of

     

       3
       3
       +
       This section has been moved to [CONTRIBUTING.md](https://github.com/NixOS/nixpkgs/blob/master/CONTRIBUTING.md).

     

       191
       4
        
       

     

       192
       192
       -
         ```nix

     

       193
       193
       -
         buildInputs = if stdenv.isDarwin then [ iconv ] else null;

     

       194
       194
       -
         ```

     

       5
       5
       +
       ## Syntax {#sec-syntax}

     

       195
       6
        
       

     

       196
       196
       -
         As an exception, an explicit conditional expression with null can be used when fixing a important bug without triggering a mass rebuild.

     

       197
       197
       -
         If this is done a follow up pull request _should_ be created to change the code to `lib.optional(s)`.

     

       198
       198
       -
       

     

       199
       199
       -
       - Arguments should be listed in the order they are used, with the exception of `lib`, which always goes first.

     

       7
       7
       +
       This section has been moved to [CONTRIBUTING.md](https://github.com/NixOS/nixpkgs/blob/master/CONTRIBUTING.md).

     

       200
       8
        
       

     

       201
       9
        
       ## Package naming {#sec-package-naming}

     

       202
       10
        
       

     

       203
       203
       -
       The key words _must_, _must not_, _required_, _shall_, _shall not_, _should_, _should not_, _recommended_, _may_, and _optional_ in this section are to be interpreted as described in [RFC 2119](https://tools.ietf.org/html/rfc2119). Only _emphasized_ words are to be interpreted in this way.

     

       204
       204
       -
       

     

       205
       205
       -
       In Nixpkgs, there are generally three different names associated with a package:

     

       206
       206
       -
       

     

       207
       207
       -
       - The `pname` attribute of the derivation. This is what most users see, in particular when using `nix-env`.

     

       208
       208
       -
       

     

       209
       209
       -
       - The variable name used for the instantiated package in `all-packages.nix`, and when passing it as a dependency to other functions. Typically this is called the _package attribute name_. This is what Nix expression authors see. It can also be used when installing using `nix-env -iA`.

     

       210
       210
       -
       

     

       211
       211
       -
       - The filename for (the directory containing) the Nix expression.

     

       212
       212
       -
       

     

       213
       213
       -
       Most of the time, these are the same. For instance, the package `e2fsprogs` has a `pname` attribute `"e2fsprogs"`, is bound to the variable name `e2fsprogs` in `all-packages.nix`, and the Nix expression is in `pkgs/os-specific/linux/e2fsprogs/default.nix`.

     

       214
       214
       -
       

     

       215
       215
       -
       There are a few naming guidelines:

     

       216
       216
       -
       

     

       217
       217
       -
       - The `pname` attribute _should_ be identical to the upstream package name.

     

       218
       218
       -
       

     

       219
       219
       -
       - The `pname` and the `version` attribute _must not_ contain uppercase letters — e.g., `"mplayer" instead of `"MPlayer"`.

     

       220
       220
       -
       

     

       221
       221
       -
       - The `version` attribute _must_ start with a digit e.g`"0.3.1rc2".

     

       222
       222
       -
       

     

       223
       223
       -
       - If a package is a commit from a repository without a version assigned, then the `version` attribute _should_ be the latest upstream version preceding that commit, followed by `-unstable-` and the date of the (fetched) commit. The date _must_ be in `"YYYY-MM-DD"` format.

     

       224
       224
       -
       

     

       225
       225
       -
       Example: Given a project had its latest releases `2.2` in November 2021, and `3.0` in January 2022, a commit authored on March 15, 2022 for an upcoming bugfix release `2.2.1` would have `version = "2.2-unstable-2022-03-15"`.

     

       226
       226
       -
       

     

       227
       227
       -
       - Dashes in the package `pname` _should_ be preserved in new variable names, rather than converted to underscores or camel cased — e.g., `http-parser` instead of `http_parser` or `httpParser`. The hyphenated style is preferred in all three package names.

     

       228
       228
       -
       

     

       229
       229
       -
       - If there are multiple versions of a package, this _should_ be reflected in the variable names in `all-packages.nix`, e.g. `json-c_0_9` and `json-c_0_11`. If there is an obvious “default” version, make an attribute like `json-c = json-c_0_9;`. See also [](#sec-versioning)

     

       11
       11
       +
       This section has been moved to [pkgs/README.md](https://github.com/NixOS/nixpkgs/blob/master/pkgs/README.md).

     

       230
       12
        
       

     

       231
       13
        
       ## File naming and organisation {#sec-organisation}

     

       232
       14
        
       

     

       233
       233
       -
       Names of files and directories should be in lowercase, with dashes between words — not in camel case. For instance, it should be `all-packages.nix`, not `allPackages.nix` or `AllPackages.nix`.

     

       234
       234
       -
       

     

       235
       235
       -
       ### Hierarchy {#sec-hierarchy}

     

       236
       236
       -
       

     

       237
       237
       -
       Each package should be stored in its own directory somewhere in the `pkgs/` tree, i.e. in `pkgs/category/subcategory/.../pkgname`. Below are some rules for picking the right category for a package. Many packages fall under several categories; what matters is the _primary_ purpose of a package. For example, the `libxml2` package builds both a library and some tools; but it’s a library foremost, so it goes under `pkgs/development/libraries`.

     

       238
       238
       -
       

     

       239
       239
       -
       When in doubt, consider refactoring the `pkgs/` tree, e.g. creating new categories or splitting up an existing category.

     

       240
       240
       -
       

     

       241
       241
       -
       **If it’s used to support _software development_:**

     

       242
       242
       -
       

     

       243
       243
       -
       - **If it’s a _library_ used by other packages:**

     

       244
       244
       -
       

     

       245
       245
       -
         - `development/libraries` (e.g. `libxml2`)

     

       246
       246
       -
       

     

       247
       247
       -
       - **If it’s a _compiler_:**

     

       248
       248
       -
       

     

       249
       249
       -
         - `development/compilers` (e.g. `gcc`)

     

       250
       250
       -
       

     

       251
       251
       -
       - **If it’s an _interpreter_:**

     

       252
       252
       -
       

     

       253
       253
       -
         - `development/interpreters` (e.g. `guile`)

     

       254
       254
       -
       

     

       255
       255
       -
       - **If it’s a (set of) development _tool(s)_:**

     

       256
       256
       -
       

     

       257
       257
       -
         - **If it’s a _parser generator_ (including lexers):**

     

       258
       258
       -
       

     

       259
       259
       -
           - `development/tools/parsing` (e.g. `bison`, `flex`)

     

       260
       260
       -
       

     

       261
       261
       -
         - **If it’s a _build manager_:**

     

       262
       262
       -
       

     

       263
       263
       -
           - `development/tools/build-managers` (e.g. `gnumake`)

     

       264
       264
       -
       

     

       265
       265
       -
         - **If it’s a _language server_:**

     

       266
       266
       -
       

     

       267
       267
       -
           - `development/tools/language-servers` (e.g. `ccls` or `rnix-lsp`)

     

       268
       268
       -
       

     

       269
       269
       -
         - **Else:**

     

       270
       270
       -
       

     

       271
       271
       -
           - `development/tools/misc` (e.g. `binutils`)

     

       272
       272
       -
       

     

       273
       273
       -
       - **Else:**

     

       274
       274
       -
       

     

       275
       275
       -
         - `development/misc`

     

       276
       276
       -
       

     

       277
       277
       -
       **If it’s a (set of) _tool(s)_:**

     

       278
       278
       -
       

     

       279
       279
       -
       (A tool is a relatively small program, especially one intended to be used non-interactively.)

     

       280
       280
       -
       

     

       281
       281
       -
       - **If it’s for _networking_:**

     

       282
       282
       -
       

     

       283
       283
       -
         - `tools/networking` (e.g. `wget`)

     

       284
       284
       -
       

     

       285
       285
       -
       - **If it’s for _text processing_:**

     

       286
       286
       -
       

     

       287
       287
       -
         - `tools/text` (e.g. `diffutils`)

     

       288
       288
       -
       

     

       289
       289
       -
       - **If it’s a _system utility_, i.e., something related or essential to the operation of a system:**

     

       290
       290
       -
       

     

       291
       291
       -
         - `tools/system` (e.g. `cron`)

     

       292
       292
       -
       

     

       293
       293
       -
       - **If it’s an _archiver_ (which may include a compression function):**

     

       294
       294
       -
       

     

       295
       295
       -
         - `tools/archivers` (e.g. `zip`, `tar`)

     

       296
       296
       -
       

     

       297
       297
       -
       - **If it’s a _compression_ program:**

     

       298
       298
       -
       

     

       299
       299
       -
         - `tools/compression` (e.g. `gzip`, `bzip2`)

     

       300
       300
       -
       

     

       301
       301
       -
       - **If it’s a _security_-related program:**

     

       302
       302
       -
       

     

       303
       303
       -
         - `tools/security` (e.g. `nmap`, `gnupg`)

     

       304
       304
       -
       

     

       305
       305
       -
       - **Else:**

     

       306
       306
       -
       

     

       307
       307
       -
         - `tools/misc`

     

       308
       308
       -
       

     

       309
       309
       -
       **If it’s a _shell_:**

     

       310
       310
       -
       

     

       311
       311
       -
       - `shells` (e.g. `bash`)

     

       312
       312
       -
       

     

       313
       313
       -
       **If it’s a _server_:**

     

       314
       314
       -
       

     

       315
       315
       -
       - **If it’s a web server:**

     

       316
       316
       -
       

     

       317
       317
       -
         - `servers/http` (e.g. `apache-httpd`)

     

       318
       318
       -
       

     

       319
       319
       -
       - **If it’s an implementation of the X Windowing System:**

     

       320
       320
       -
       

     

       321
       321
       -
         - `servers/x11` (e.g. `xorg` — this includes the client libraries and programs)

     

       322
       322
       -
       

     

       323
       323
       -
       - **Else:**

     

       324
       324
       -
       

     

       325
       325
       -
         - `servers/misc`

     

       326
       326
       -
       

     

       327
       327
       -
       **If it’s a _desktop environment_:**

     

       328
       328
       -
       

     

       329
       329
       -
       - `desktops` (e.g. `kde`, `gnome`, `enlightenment`)

     

       330
       330
       -
       

     

       331
       331
       -
       **If it’s a _window manager_:**

     

       332
       332
       -
       

     

       333
       333
       -
       - `applications/window-managers` (e.g. `awesome`, `stumpwm`)

     

       334
       334
       -
       

     

       335
       335
       -
       **If it’s an _application_:**

     

       336
       336
       -
       

     

       337
       337
       -
       A (typically large) program with a distinct user interface, primarily used interactively.

     

       338
       338
       -
       

     

       339
       339
       -
       - **If it’s a _version management system_:**

     

       340
       340
       -
       

     

       341
       341
       -
         - `applications/version-management` (e.g. `subversion`)

     

       342
       342
       -
       

     

       343
       343
       -
       - **If it’s a _terminal emulator_:**

     

       344
       344
       -
       

     

       345
       345
       -
         - `applications/terminal-emulators` (e.g. `alacritty` or `rxvt` or `termite`)

     

       346
       346
       -
       

     

       347
       347
       -
       - **If it’s a _file manager_:**

     

       348
       348
       -
       

     

       349
       349
       -
         - `applications/file-managers` (e.g. `mc` or `ranger` or `pcmanfm`)

     

       350
       350
       -
       

     

       351
       351
       -
       - **If it’s for _video playback / editing_:**

     

       352
       352
       -
       

     

       353
       353
       -
         - `applications/video` (e.g. `vlc`)

     

       354
       354
       -
       

     

       355
       355
       -
       - **If it’s for _graphics viewing / editing_:**

     

       356
       356
       -
       

     

       357
       357
       -
         - `applications/graphics` (e.g. `gimp`)

     

       358
       358
       -
       

     

       359
       359
       -
       - **If it’s for _networking_:**

     

       360
       360
       -
       

     

       361
       361
       -
         - **If it’s a _mailreader_:**

     

       362
       362
       -
       

     

       363
       363
       -
           - `applications/networking/mailreaders` (e.g. `thunderbird`)

     

       364
       364
       -
       

     

       365
       365
       -
         - **If it’s a _newsreader_:**

     

       366
       366
       -
       

     

       367
       367
       -
           - `applications/networking/newsreaders` (e.g. `pan`)

     

       368
       368
       -
       

     

       369
       369
       -
         - **If it’s a _web browser_:**

     

       370
       370
       -
       

     

       371
       371
       -
           - `applications/networking/browsers` (e.g. `firefox`)

     

       372
       372
       -
       

     

       373
       373
       -
         - **Else:**

     

       374
       374
       -
       

     

       375
       375
       -
           - `applications/networking/misc`

     

       376
       376
       -
       

     

       377
       377
       -
       - **Else:**

     

       378
       378
       -
       

     

       379
       379
       -
         - `applications/misc`

     

       380
       380
       -
       

     

       381
       381
       -
       **If it’s _data_ (i.e., does not have a straight-forward executable semantics):**

     

       382
       382
       -
       

     

       383
       383
       -
       - **If it’s a _font_:**

     

       384
       384
       -
       

     

       385
       385
       -
         - `data/fonts`

     

       386
       386
       -
       

     

       387
       387
       -
       - **If it’s an _icon theme_:**

     

       388
       388
       -
       

     

       389
       389
       -
         - `data/icons`

     

       390
       390
       -
       

     

       391
       391
       -
       - **If it’s related to _SGML/XML processing_:**

     

       392
       392
       -
       

     

       393
       393
       -
         - **If it’s an _XML DTD_:**

     

       394
       394
       -
       

     

       395
       395
       -
           - `data/sgml+xml/schemas/xml-dtd` (e.g. `docbook`)

     

       396
       396
       -
       

     

       397
       397
       -
         - **If it’s an _XSLT stylesheet_:**

     

       398
       398
       -
       

     

       399
       399
       -
           (Okay, these are executable...)

     

       400
       400
       -
       

     

       401
       401
       -
           - `data/sgml+xml/stylesheets/xslt` (e.g. `docbook-xsl`)

     

       402
       402
       -
       

     

       403
       403
       -
       - **If it’s a _theme_ for a _desktop environment_, a _window manager_ or a _display manager_:**

     

       404
       404
       -
       

     

       405
       405
       -
         - `data/themes`

     

       406
       406
       -
       

     

       407
       407
       -
       **If it’s a _game_:**

     

       408
       408
       -
       

     

       409
       409
       -
       - `games`

     

       410
       410
       -
       

     

       411
       411
       -
       **Else:**

     

       412
       412
       -
       

     

       413
       413
       -
       - `misc`

     

       15
       15
       +
       This section has been moved to [CONTRIBUTING.md](https://github.com/NixOS/nixpkgs/blob/master/CONTRIBUTING.md).

     

       414
       16
        
       

     

       415
       17
        
       ### Versioning {#sec-versioning}

     

       416
       18
        
       

     

       417
       417
       -
       Because every version of a package in Nixpkgs creates a potential maintenance burden, old versions of a package should not be kept unless there is a good reason to do so. For instance, Nixpkgs contains several versions of GCC because other packages don’t build with the latest version of GCC. Other examples are having both the latest stable and latest pre-release version of a package, or to keep several major releases of an application that differ significantly in functionality.

     

       418
       418
       -
       

     

       419
       419
       -
       If there is only one version of a package, its Nix expression should be named `e2fsprogs/default.nix`. If there are multiple versions, this should be reflected in the filename, e.g. `e2fsprogs/1.41.8.nix` and `e2fsprogs/1.41.9.nix`. The version in the filename should leave out unnecessary detail. For instance, if we keep the latest Firefox 2.0.x and 3.5.x versions in Nixpkgs, they should be named `firefox/2.0.nix` and `firefox/3.5.nix`, respectively (which, at a given point, might contain versions `2.0.0.20` and `3.5.4`). If a version requires many auxiliary files, you can use a subdirectory for each version, e.g. `firefox/2.0/default.nix` and `firefox/3.5/default.nix`.

     

       420
       420
       -
       

     

       421
       421
       -
       All versions of a package _must_ be included in `all-packages.nix` to make sure that they evaluate correctly.

     

       19
       19
       +
       This section has been moved to [pkgs/README.md](https://github.com/NixOS/nixpkgs/blob/master/pkgs/README.md).

     

       422
       20
        
       

     

       423
       21
        
       ## Fetching Sources {#sec-sources}

     

       424
       22
        
       

     

       425
       425
       -
       There are multiple ways to fetch a package source in nixpkgs. The general guideline is that you should package reproducible sources with a high degree of availability. Right now there is only one fetcher which has mirroring support and that is `fetchurl`. Note that you should also prefer protocols which have a corresponding proxy environment variable.

     

       426
       426
       -
       

     

       427
       427
       -
       You can find many source fetch helpers in `pkgs/build-support/fetch*`.

     

       428
       428
       -
       

     

       429
       429
       -
       In the file `pkgs/top-level/all-packages.nix` you can find fetch helpers, these have names on the form `fetchFrom*`. The intention of these are to provide snapshot fetches but using the same api as some of the version controlled fetchers from `pkgs/build-support/`. As an example going from bad to good:

     

       430
       430
       -
       

     

       431
       431
       -
       - Bad: Uses `git://` which won't be proxied.

     

       432
       432
       -
       

     

       433
       433
       -
         ```nix

     

       434
       434
       -
         src = fetchgit {

     

       435
       435
       -
           url = "git@github.com:NixOS/nix.git"

     

       436
       436
       -
           url = "git://github.com/NixOS/nix.git";

     

       437
       437
       -
           rev = "1f795f9f44607cc5bec70d1300150bfefcef2aae";

     

       438
       438
       -
           hash = "sha256-7D4m+saJjbSFP5hOwpQq2FGR2rr+psQMTcyb1ZvtXsQ=";

     

       439
       439
       -
         }

     

       440
       440
       -
         ```

     

       441
       441
       -
       

     

       442
       442
       -
       - Better: This is ok, but an archive fetch will still be faster.

     

       443
       443
       -
       

     

       444
       444
       -
         ```nix

     

       445
       445
       -
         src = fetchgit {

     

       446
       446
       -
           url = "https://github.com/NixOS/nix.git";

     

       447
       447
       -
           rev = "1f795f9f44607cc5bec70d1300150bfefcef2aae";

     

       448
       448
       -
           hash = "sha256-7D4m+saJjbSFP5hOwpQq2FGR2rr+psQMTcyb1ZvtXsQ=";

     

       449
       449
       -
         }

     

       450
       450
       -
         ```

     

       451
       451
       -
       

     

       452
       452
       -
       - Best: Fetches a snapshot archive and you get the rev you want.

     

       453
       453
       -
       

     

       454
       454
       -
         ```nix

     

       455
       455
       -
         src = fetchFromGitHub {

     

       456
       456
       -
           owner = "NixOS";

     

       457
       457
       -
           repo = "nix";

     

       458
       458
       -
           rev = "1f795f9f44607cc5bec70d1300150bfefcef2aae";

     

       459
       459
       -
           hash = "sha256-7D4m+saJjbSFP5hOwpQq2FGR2rr+psQMTcyb1ZvtXsQ=";

     

       460
       460
       -
         }

     

       461
       461
       -
         ```

     

       462
       462
       -
       

     

       463
       463
       -
       When fetching from GitHub, commits must always be referenced by their full commit hash. This is because GitHub shares commit hashes among all forks and returns `404 Not Found` when a short commit hash is ambiguous. It already happens for some short, 6-character commit hashes in `nixpkgs`.

     

       464
       464
       -
       It is a practical vector for a denial-of-service attack by pushing large amounts of auto generated commits into forks and was already [demonstrated against GitHub Actions Beta](https://blog.teddykatz.com/2019/11/12/github-actions-dos.html).

     

       465
       465
       -
       

     

       466
       466
       -
       Find the value to put as `hash` by running `nix-shell -p nix-prefetch-github --run "nix-prefetch-github --rev 1f795f9f44607cc5bec70d1300150bfefcef2aae NixOS nix"`.

     

       23
       23
       +
       This section has been moved to [pkgs/README.md](https://github.com/NixOS/nixpkgs/blob/master/pkgs/README.md).

     

       467
       24
        
       

     

       468
       25
        
       ## Obtaining source hash {#sec-source-hashes}

     

       469
       26
        
       

     

       470
       470
       -
       Preferred source hash type is sha256. There are several ways to get it.

     

       471
       471
       -
       

     

       472
       472
       -
       1. Prefetch URL (with `nix-prefetch-XXX URL`, where `XXX` is one of `url`, `git`, `hg`, `cvs`, `bzr`, `svn`). Hash is printed to stdout.

     

       473
       473
       -
       

     

       474
       474
       -
       2. Prefetch by package source (with `nix-prefetch-url '<nixpkgs>' -A PACKAGE.src`, where `PACKAGE` is package attribute name). Hash is printed to stdout.

     

       475
       475
       -
       

     

       476
       476
       -
           This works well when you've upgraded existing package version and want to find out new hash, but is useless if package can't be accessed by attribute or package has multiple sources (`.srcs`, architecture-dependent sources, etc).

     

       477
       477
       -
       

     

       478
       478
       -
       3. Upstream provided hash: use it when upstream provides `sha256` or `sha512` (when upstream provides `md5`, don't use it, compute `sha256` instead).

     

       479
       479
       -
       

     

       480
       480
       -
           A little nuance is that `nix-prefetch-*` tools produce hash encoded with `base32`, but upstream usually provides hexadecimal (`base16`) encoding. Fetchers understand both formats. Nixpkgs does not standardize on any one format.

     

       481
       481
       -
       

     

       482
       482
       -
           You can convert between formats with nix-hash, for example:

     

       483
       483
       -
       

     

       484
       484
       -
           ```ShellSession

     

       485
       485
       -
           $ nix-hash --type sha256 --to-base32 HASH

     

       486
       486
       -
           ```

     

       487
       487
       -
       

     

       488
       488
       -
       4. Extracting hash from local source tarball can be done with `sha256sum`. Use `nix-prefetch-url file:///path/to/tarball` if you want base32 hash.

     

       489
       489
       -
       

     

       490
       490
       -
       5. Fake hash: set the hash to one of

     

       491
       491
       -
       

     

       492
       492
       -
          - `""`

     

       493
       493
       -
          - `lib.fakeHash`

     

       494
       494
       -
          - `lib.fakeSha256`

     

       495
       495
       -
          - `lib.fakeSha512`

     

       496
       496
       -
       

     

       497
       497
       -
          in the package expression, attempt build and extract correct hash from error messages.

     

       498
       498
       -
       

     

       499
       499
       -
          ::: {.warning}

     

       500
       500
       -
          You must use one of these four fake hashes and not some arbitrarily-chosen hash.

     

       501
       501
       -
       

     

       502
       502
       -
          See [](#sec-source-hashes-security).

     

       503
       503
       -
          :::

     

       504
       504
       -
       

     

       505
       505
       -
           This is last resort method when reconstructing source URL is non-trivial and `nix-prefetch-url -A` isn’t applicable (for example, [one of `kodi` dependencies](https://github.com/NixOS/nixpkgs/blob/d2ab091dd308b99e4912b805a5eb088dd536adb9/pkgs/applications/video/kodi/default.nix#L73)). The easiest way then would be replace hash with a fake one and rebuild. Nix build will fail and error message will contain desired hash.

     

       506
       506
       -
       

     

       27
       27
       +
       This section has been moved to [pkgs/README.md](https://github.com/NixOS/nixpkgs/blob/master/pkgs/README.md).

     

       507
       28
        
       

     

       508
       29
        
       ### Obtaining hashes securely {#sec-source-hashes-security}

     

       509
       30
        
       

     

       510
       510
       -
       Let's say Man-in-the-Middle (MITM) sits close to your network. Then instead of fetching source you can fetch malware, and instead of source hash you get hash of malware. Here are security considerations for this scenario:

     

       511
       511
       -
       

     

       512
       512
       -
       - `http://` URLs are not secure to prefetch hash from;

     

       513
       513
       -
       

     

       514
       514
       -
       - hashes from upstream (in method 3) should be obtained via secure protocol;

     

       515
       515
       -
       

     

       516
       516
       -
       - `https://` URLs are secure in methods 1, 2, 3;

     

       517
       517
       -
       

     

       518
       518
       -
       - `https://` URLs are secure in method 5 *only if* you use one of the listed fake hashes. If you use any other hash, `fetchurl` will pass `--insecure` to `curl` and may then degrade to HTTP in case of TLS certificate expiration.

     

       31
       31
       +
       This section has been moved to [pkgs/README.md](https://github.com/NixOS/nixpkgs/blob/master/pkgs/README.md).

     

       519
       32
        
       

     

       520
       33
        
       ## Patches {#sec-patches}

     

       521
       34
        
       

     

       522
       522
       -
       Patches available online should be retrieved using `fetchpatch`.

     

       523
       523
       -
       

     

       524
       524
       -
       ```nix

     

       525
       525
       -
       patches = [

     

       526
       526
       -
         (fetchpatch {

     

       527
       527
       -
           name = "fix-check-for-using-shared-freetype-lib.patch";

     

       528
       528
       -
           url = "http://git.ghostscript.com/?p=ghostpdl.git;a=patch;h=8f5d285";

     

       529
       529
       -
           hash = "sha256-uRcxaCjd+WAuGrXOmGfFeu79cUILwkRdBu48mwcBE7g=";

     

       530
       530
       -
         })

     

       531
       531
       -
       ];

     

       532
       532
       -
       ```

     

       533
       533
       -
       

     

       534
       534
       -
       Otherwise, you can add a `.patch` file to the `nixpkgs` repository. In the interest of keeping our maintenance burden to a minimum, only patches that are unique to `nixpkgs` should be added in this way.

     

       535
       535
       -
       

     

       536
       536
       -
       If a patch is available online but does not cleanly apply, it can be modified in some fixed ways by using additional optional arguments for `fetchpatch`. Check [](#fetchpatch) for details.

     

       537
       537
       -
       

     

       538
       538
       -
       ```nix

     

       539
       539
       -
       patches = [ ./0001-changes.patch ];

     

       540
       540
       -
       ```

     

       541
       541
       -
       

     

       542
       542
       -
       If you do need to do create this sort of patch file, one way to do so is with git:

     

       543
       543
       -
       

     

       544
       544
       -
       1. Move to the root directory of the source code you're patching.

     

       545
       545
       -
       

     

       546
       546
       -
           ```ShellSession

     

       547
       547
       -
           $ cd the/program/source

     

       548
       548
       -
           ```

     

       549
       549
       -
       

     

       550
       550
       -
       2. If a git repository is not already present, create one and stage all of the source files.

     

       551
       551
       -
       

     

       552
       552
       -
           ```ShellSession

     

       553
       553
       -
           $ git init

     

       554
       554
       -
           $ git add .

     

       555
       555
       -
           ```

     

       556
       556
       -
       

     

       557
       557
       -
       3. Edit some files to make whatever changes need to be included in the patch.

     

       558
       558
       -
       

     

       559
       559
       -
       4. Use git to create a diff, and pipe the output to a patch file:

     

       560
       560
       -
       

     

       561
       561
       -
           ```ShellSession

     

       562
       562
       -
           $ git diff -a > nixpkgs/pkgs/the/package/0001-changes.patch

     

       563
       563
       -
           ```

     

       35
       35
       +
       This section has been moved to [pkgs/README.md](https://github.com/NixOS/nixpkgs/blob/master/pkgs/README.md).

     

       564
       36
        
       

     

       565
       37
        
       ## Package tests {#sec-package-tests}

     

       566
       38
        
       

     

       567
       567
       -
       Tests are important to ensure quality and make reviews and automatic updates easy.

     

       568
       568
       -
       

     

       569
       569
       -
       The following types of tests exists:

     

       570
       570
       -
       

     

       571
       571
       -
       * [NixOS **module tests**](https://nixos.org/manual/nixos/stable/#sec-nixos-tests), which spawn one or more NixOS VMs. They exercise both NixOS modules and the packaged programs used within them. For example, a NixOS module test can start a web server VM running the `nginx` module, and a client VM running `curl` or a graphical `firefox`, and test that they can talk to each other and display the correct content.

     

       572
       572
       -
       * Nix **package tests** are a lightweight alternative to NixOS module tests. They should be used to create simple integration tests for packages, but cannot test NixOS services, and some programs with graphical user interfaces may also be difficult to test with them.

     

       573
       573
       -
       * The **`checkPhase` of a package**, which should execute the unit tests that are included in the source code of a package.

     

       574
       574
       -
       

     

       575
       575
       -
       Here in the nixpkgs manual we describe mostly _package tests_; for _module tests_ head over to the corresponding [section in the NixOS manual](https://nixos.org/manual/nixos/stable/#sec-nixos-tests).

     

       39
       39
       +
       This section has been moved to [pkgs/README.md](https://github.com/NixOS/nixpkgs/blob/master/pkgs/README.md).

     

       576
       40
        
       

     

       577
       41
        
       ### Writing inline package tests {#ssec-inline-package-tests-writing}

     

       578
       42
        
       

     

       579
       579
       -
       For very simple tests, they can be written inline:

     

       580
       580
       -
       

     

       581
       581
       -
       ```nix

     

       582
       582
       -
       { …, yq-go }:

     

       583
       583
       -
       

     

       584
       584
       -
       buildGoModule rec {

     

       585
       585
       -
         …

     

       586
       586
       -
       

     

       587
       587
       -
         passthru.tests = {

     

       588
       588
       -
           simple = runCommand "${pname}-test" {} ''

     

       589
       589
       -
             echo "test: 1" | ${yq-go}/bin/yq eval -j > $out

     

       590
       590
       -
             [ "$(cat $out | tr -d $'\n ')" = '{"test":1}' ]

     

       591
       591
       -
           '';

     

       592
       592
       -
         };

     

       593
       593
       -
       }

     

       594
       594
       -
       ```

     

       43
       43
       +
       This section has been moved to [pkgs/README.md](https://github.com/NixOS/nixpkgs/blob/master/pkgs/README.md).

     

       595
       44
        
       

     

       596
       45
        
       ### Writing larger package tests {#ssec-package-tests-writing}

     

       597
       46
        
       

     

       598
       598
       -
       This is an example using the `phoronix-test-suite` package with the current best practices.

     

       599
       599
       -
       

     

       600
       600
       -
       Add the tests in `passthru.tests` to the package definition like this:

     

       601
       601
       -
       

     

       602
       602
       -
       ```nix

     

       603
       603
       -
       { stdenv, lib, fetchurl, callPackage }:

     

       604
       604
       -
       

     

       605
       605
       -
       stdenv.mkDerivation {

     

       606
       606
       -
         …

     

       607
       607
       -
       

     

       608
       608
       -
         passthru.tests = {

     

       609
       609
       -
           simple-execution = callPackage ./tests.nix { };

     

       610
       610
       -
         };

     

       611
       611
       -
       

     

       612
       612
       -
         meta = { … };

     

       613
       613
       -
       }

     

       614
       614
       -
       ```

     

       615
       615
       -
       

     

       616
       616
       -
       Create `tests.nix` in the package directory:

     

       617
       617
       -
       

     

       618
       618
       -
       ```nix

     

       619
       619
       -
       { runCommand, phoronix-test-suite }:

     

       620
       620
       -
       

     

       621
       621
       -
       let

     

       622
       622
       -
         inherit (phoronix-test-suite) pname version;

     

       623
       623
       -
       in

     

       624
       624
       -
       

     

       625
       625
       -
       runCommand "${pname}-tests" { meta.timeout = 60; }

     

       626
       626
       -
         ''

     

       627
       627
       -
           # automatic initial setup to prevent interactive questions

     

       628
       628
       -
           ${phoronix-test-suite}/bin/phoronix-test-suite enterprise-setup >/dev/null

     

       629
       629
       -
           # get version of installed program and compare with package version

     

       630
       630
       -
           if [[ `${phoronix-test-suite}/bin/phoronix-test-suite version` != *"${version}"*  ]]; then

     

       631
       631
       -
             echo "Error: program version does not match package version"

     

       632
       632
       -
             exit 1

     

       633
       633
       -
           fi

     

       634
       634
       -
           # run dummy command

     

       635
       635
       -
           ${phoronix-test-suite}/bin/phoronix-test-suite dummy_module.dummy-command >/dev/null

     

       636
       636
       -
           # needed for Nix to register the command as successful

     

       637
       637
       -
           touch $out

     

       638
       638
       -
         ''

     

       639
       639
       -
       ```

     

       47
       47
       +
       This section has been moved to [pkgs/README.md](https://github.com/NixOS/nixpkgs/blob/master/pkgs/README.md).

     

       640
       48
        
       

     

       641
       49
        
       ### Running package tests {#ssec-package-tests-running}

     

       642
       50
        
       

     

       643
       643
       -
       You can run these tests with:

     

       644
       644
       -
       

     

       645
       645
       -
       ```ShellSession

     

       646
       646
       -
       $ cd path/to/nixpkgs

     

       647
       647
       -
       $ nix-build -A phoronix-test-suite.tests

     

       648
       648
       -
       ```

     

       51
       51
       +
       This section has been moved to [pkgs/README.md](https://github.com/NixOS/nixpkgs/blob/master/pkgs/README.md).

     

       649
       52
        
       

     

       650
       53
        
       ### Examples of package tests {#ssec-package-tests-examples}

     

       651
       54
        
       

     

       652
       652
       -
       Here are examples of package tests:

     

       653
       653
       -
       

     

       654
       654
       -
       - [Jasmin compile test](https://github.com/NixOS/nixpkgs/blob/master/pkgs/development/compilers/jasmin/test-assemble-hello-world/default.nix)

     

       655
       655
       -
       - [Lobster compile test](https://github.com/NixOS/nixpkgs/blob/master/pkgs/development/compilers/lobster/test-can-run-hello-world.nix)

     

       656
       656
       -
       - [Spacy annotation test](https://github.com/NixOS/nixpkgs/blob/master/pkgs/development/python-modules/spacy/annotation-test/default.nix)

     

       657
       657
       -
       - [Libtorch test](https://github.com/NixOS/nixpkgs/blob/master/pkgs/development/libraries/science/math/libtorch/test/default.nix)

     

       658
       658
       -
       - [Multiple tests for nanopb](https://github.com/NixOS/nixpkgs/blob/master/pkgs/development/libraries/nanopb/default.nix)

     

       55
       55
       +
       This section has been moved to [pkgs/README.md](https://github.com/NixOS/nixpkgs/blob/master/pkgs/README.md).

     

       659
       56
        
       

     

       660
       57
        
       ### Linking NixOS module tests to a package {#ssec-nixos-tests-linking}

     

       661
       58
        
       

     

       662
       662
       -
       Like [package tests](#ssec-package-tests-writing) as shown above, [NixOS module tests](https://nixos.org/manual/nixos/stable/#sec-nixos-tests) can also be linked to a package, so that the tests can be easily run when changing the related package.

     

       663
       663
       -
       

     

       664
       664
       -
       For example, assuming we're packaging `nginx`, we can link its module test via `passthru.tests`:

     

       665
       665
       -
       

     

       666
       666
       -
       ```nix

     

       667
       667
       -
       { stdenv, lib, nixosTests }:

     

       668
       668
       -
       

     

       669
       669
       -
       stdenv.mkDerivation {

     

       670
       670
       -
         ...

     

       671
       671
       -
       

     

       672
       672
       -
         passthru.tests = {

     

       673
       673
       -
           nginx = nixosTests.nginx;

     

       674
       674
       -
         };

     

       675
       675
       -
       

     

       676
       676
       -
         ...

     

       677
       677
       -
       }

     

       678
       678
       -
       ```

     

       59
       59
       +
       This section has been moved to [pkgs/README.md](https://github.com/NixOS/nixpkgs/blob/master/pkgs/README.md).

     

       679
       60
        
       

     

       680
       61
        
       ### Import From Derivation {#ssec-import-from-derivation}

     

       681
       62
        
       

     

       682
       682
       -
       Import From Derivation (IFD) is disallowed in Nixpkgs for performance reasons:

     

       683
       683
       -
       [Hydra] evaluates the entire package set, and sequential builds during evaluation would increase evaluation times to become impractical.

     

       684
       684
       -
       

     

       685
       685
       -
       [Hydra]: https://github.com/NixOS/hydra

     

       686
       686
       -
       

     

       687
       687
       -
       Import From Derivation can be worked around in some cases by committing generated intermediate files to version control and reading those instead.

     

       688
       688
       -
       

     

       689
       689
       -
       <!-- TODO: remove the following and link to Nix manual once https://github.com/NixOS/nix/pull/7332 is merged -->

     

       690
       690
       -
       

     

       691
       691
       -
       See also [NixOS Wiki: Import From Derivation].

     

       692
       692
       -
       

     

       693
       693
       -
       [NixOS Wiki: Import From Derivation]: https://nixos.wiki/wiki/Import_From_Derivation

     

       63
       63
       +
       This section has been moved to [pkgs/README.md](https://github.com/NixOS/nixpkgs/blob/master/pkgs/README.md).

+493 -1

pkgs/README.md

···

       1
       1
        
       # Contributing to Nixpkgs packages

     

       2
       2
        
       

     

       3
       3
       +
       ## Hierarchy {#sec-hierarchy}

     

       4
       4
       +
       

     

       5
       5
       +
       Each package should be stored in its own directory somewhere in the `pkgs/` tree, i.e. in `pkgs/category/subcategory/.../pkgname`. Below are some rules for picking the right category for a package. Many packages fall under several categories; what matters is the _primary_ purpose of a package. For example, the `libxml2` package builds both a library and some tools; but it’s a library foremost, so it goes under `pkgs/development/libraries`.

     

       6
       6
       +
       

     

       7
       7
       +
       When in doubt, consider refactoring the `pkgs/` tree, e.g. creating new categories or splitting up an existing category.

     

       8
       8
       +
       

     

       9
       9
       +
       **If it’s used to support _software development_:**

     

       10
       10
       +
       

     

       11
       11
       +
       - **If it’s a _library_ used by other packages:**

     

       12
       12
       +
       

     

       13
       13
       +
         - `development/libraries` (e.g. `libxml2`)

     

       14
       14
       +
       

     

       15
       15
       +
       - **If it’s a _compiler_:**

     

       16
       16
       +
       

     

       17
       17
       +
         - `development/compilers` (e.g. `gcc`)

     

       18
       18
       +
       

     

       19
       19
       +
       - **If it’s an _interpreter_:**

     

       20
       20
       +
       

     

       21
       21
       +
         - `development/interpreters` (e.g. `guile`)

     

       22
       22
       +
       

     

       23
       23
       +
       - **If it’s a (set of) development _tool(s)_:**

     

       24
       24
       +
       

     

       25
       25
       +
         - **If it’s a _parser generator_ (including lexers):**

     

       26
       26
       +
       

     

       27
       27
       +
           - `development/tools/parsing` (e.g. `bison`, `flex`)

     

       28
       28
       +
       

     

       29
       29
       +
         - **If it’s a _build manager_:**

     

       30
       30
       +
       

     

       31
       31
       +
           - `development/tools/build-managers` (e.g. `gnumake`)

     

       32
       32
       +
       

     

       33
       33
       +
         - **If it’s a _language server_:**

     

       34
       34
       +
       

     

       35
       35
       +
           - `development/tools/language-servers` (e.g. `ccls` or `rnix-lsp`)

     

       36
       36
       +
       

     

       37
       37
       +
         - **Else:**

     

       38
       38
       +
       

     

       39
       39
       +
           - `development/tools/misc` (e.g. `binutils`)

     

       40
       40
       +
       

     

       41
       41
       +
       - **Else:**

     

       42
       42
       +
       

     

       43
       43
       +
         - `development/misc`

     

       44
       44
       +
       

     

       45
       45
       +
       **If it’s a (set of) _tool(s)_:**

     

       46
       46
       +
       

     

       47
       47
       +
       (A tool is a relatively small program, especially one intended to be used non-interactively.)

     

       48
       48
       +
       

     

       49
       49
       +
       - **If it’s for _networking_:**

     

       50
       50
       +
       

     

       51
       51
       +
         - `tools/networking` (e.g. `wget`)

     

       52
       52
       +
       

     

       53
       53
       +
       - **If it’s for _text processing_:**

     

       54
       54
       +
       

     

       55
       55
       +
         - `tools/text` (e.g. `diffutils`)

     

       56
       56
       +
       

     

       57
       57
       +
       - **If it’s a _system utility_, i.e., something related or essential to the operation of a system:**

     

       58
       58
       +
       

     

       59
       59
       +
         - `tools/system` (e.g. `cron`)

     

       60
       60
       +
       

     

       61
       61
       +
       - **If it’s an _archiver_ (which may include a compression function):**

     

       62
       62
       +
       

     

       63
       63
       +
         - `tools/archivers` (e.g. `zip`, `tar`)

     

       64
       64
       +
       

     

       65
       65
       +
       - **If it’s a _compression_ program:**

     

       66
       66
       +
       

     

       67
       67
       +
         - `tools/compression` (e.g. `gzip`, `bzip2`)

     

       68
       68
       +
       

     

       69
       69
       +
       - **If it’s a _security_-related program:**

     

       70
       70
       +
       

     

       71
       71
       +
         - `tools/security` (e.g. `nmap`, `gnupg`)

     

       72
       72
       +
       

     

       73
       73
       +
       - **Else:**

     

       74
       74
       +
       

     

       75
       75
       +
         - `tools/misc`

     

       76
       76
       +
       

     

       77
       77
       +
       **If it’s a _shell_:**

     

       78
       78
       +
       

     

       79
       79
       +
       - `shells` (e.g. `bash`)

     

       80
       80
       +
       

     

       81
       81
       +
       **If it’s a _server_:**

     

       82
       82
       +
       

     

       83
       83
       +
       - **If it’s a web server:**

     

       84
       84
       +
       

     

       85
       85
       +
         - `servers/http` (e.g. `apache-httpd`)

     

       86
       86
       +
       

     

       87
       87
       +
       - **If it’s an implementation of the X Windowing System:**

     

       88
       88
       +
       

     

       89
       89
       +
         - `servers/x11` (e.g. `xorg` — this includes the client libraries and programs)

     

       90
       90
       +
       

     

       91
       91
       +
       - **Else:**

     

       92
       92
       +
       

     

       93
       93
       +
         - `servers/misc`

     

       94
       94
       +
       

     

       95
       95
       +
       **If it’s a _desktop environment_:**

     

       96
       96
       +
       

     

       97
       97
       +
       - `desktops` (e.g. `kde`, `gnome`, `enlightenment`)

     

       98
       98
       +
       

     

       99
       99
       +
       **If it’s a _window manager_:**

     

       100
       100
       +
       

     

       101
       101
       +
       - `applications/window-managers` (e.g. `awesome`, `stumpwm`)

     

       102
       102
       +
       

     

       103
       103
       +
       **If it’s an _application_:**

     

       104
       104
       +
       

     

       105
       105
       +
       A (typically large) program with a distinct user interface, primarily used interactively.

     

       106
       106
       +
       

     

       107
       107
       +
       - **If it’s a _version management system_:**

     

       108
       108
       +
       

     

       109
       109
       +
         - `applications/version-management` (e.g. `subversion`)

     

       110
       110
       +
       

     

       111
       111
       +
       - **If it’s a _terminal emulator_:**

     

       112
       112
       +
       

     

       113
       113
       +
         - `applications/terminal-emulators` (e.g. `alacritty` or `rxvt` or `termite`)

     

       114
       114
       +
       

     

       115
       115
       +
       - **If it’s a _file manager_:**

     

       116
       116
       +
       

     

       117
       117
       +
         - `applications/file-managers` (e.g. `mc` or `ranger` or `pcmanfm`)

     

       118
       118
       +
       

     

       119
       119
       +
       - **If it’s for _video playback / editing_:**

     

       120
       120
       +
       

     

       121
       121
       +
         - `applications/video` (e.g. `vlc`)

     

       122
       122
       +
       

     

       123
       123
       +
       - **If it’s for _graphics viewing / editing_:**

     

       124
       124
       +
       

     

       125
       125
       +
         - `applications/graphics` (e.g. `gimp`)

     

       126
       126
       +
       

     

       127
       127
       +
       - **If it’s for _networking_:**

     

       128
       128
       +
       

     

       129
       129
       +
         - **If it’s a _mailreader_:**

     

       130
       130
       +
       

     

       131
       131
       +
           - `applications/networking/mailreaders` (e.g. `thunderbird`)

     

       132
       132
       +
       

     

       133
       133
       +
         - **If it’s a _newsreader_:**

     

       134
       134
       +
       

     

       135
       135
       +
           - `applications/networking/newsreaders` (e.g. `pan`)

     

       136
       136
       +
       

     

       137
       137
       +
         - **If it’s a _web browser_:**

     

       138
       138
       +
       

     

       139
       139
       +
           - `applications/networking/browsers` (e.g. `firefox`)

     

       140
       140
       +
       

     

       141
       141
       +
         - **Else:**

     

       142
       142
       +
       

     

       143
       143
       +
           - `applications/networking/misc`

     

       144
       144
       +
       

     

       145
       145
       +
       - **Else:**

     

       146
       146
       +
       

     

       147
       147
       +
         - `applications/misc`

     

       148
       148
       +
       

     

       149
       149
       +
       **If it’s _data_ (i.e., does not have a straight-forward executable semantics):**

     

       150
       150
       +
       

     

       151
       151
       +
       - **If it’s a _font_:**

     

       152
       152
       +
       

     

       153
       153
       +
         - `data/fonts`

     

       154
       154
       +
       

     

       155
       155
       +
       - **If it’s an _icon theme_:**

     

       156
       156
       +
       

     

       157
       157
       +
         - `data/icons`

     

       158
       158
       +
       

     

       159
       159
       +
       - **If it’s related to _SGML/XML processing_:**

     

       160
       160
       +
       

     

       161
       161
       +
         - **If it’s an _XML DTD_:**

     

       162
       162
       +
       

     

       163
       163
       +
           - `data/sgml+xml/schemas/xml-dtd` (e.g. `docbook`)

     

       164
       164
       +
       

     

       165
       165
       +
         - **If it’s an _XSLT stylesheet_:**

     

       166
       166
       +
       

     

       167
       167
       +
           (Okay, these are executable...)

     

       168
       168
       +
       

     

       169
       169
       +
           - `data/sgml+xml/stylesheets/xslt` (e.g. `docbook-xsl`)

     

       170
       170
       +
       

     

       171
       171
       +
       - **If it’s a _theme_ for a _desktop environment_, a _window manager_ or a _display manager_:**

     

       172
       172
       +
       

     

       173
       173
       +
         - `data/themes`

     

       174
       174
       +
       

     

       175
       175
       +
       **If it’s a _game_:**

     

       176
       176
       +
       

     

       177
       177
       +
       - `games`

     

       178
       178
       +
       

     

       179
       179
       +
       **Else:**

     

       180
       180
       +
       

     

       181
       181
       +
       - `misc`

     

       182
       182
       +
       

     

       3
       183
        
       ## (Conventions)

     

       4
       184
        
       

     

       185
       185
       +
       ### Package naming {#sec-package-naming}

     

       186
       186
       +
       

     

       187
       187
       +
       The key words _must_, _must not_, _required_, _shall_, _shall not_, _should_, _should not_, _recommended_, _may_, and _optional_ in this section are to be interpreted as described in [RFC 2119](https://tools.ietf.org/html/rfc2119). Only _emphasized_ words are to be interpreted in this way.

     

       188
       188
       +
       

     

       189
       189
       +
       In Nixpkgs, there are generally three different names associated with a package:

     

       190
       190
       +
       

     

       191
       191
       +
       - The `pname` attribute of the derivation. This is what most users see, in particular when using `nix-env`.

     

       192
       192
       +
       

     

       193
       193
       +
       - The variable name used for the instantiated package in `all-packages.nix`, and when passing it as a dependency to other functions. Typically this is called the _package attribute name_. This is what Nix expression authors see. It can also be used when installing using `nix-env -iA`.

     

       194
       194
       +
       

     

       195
       195
       +
       - The filename for (the directory containing) the Nix expression.

     

       196
       196
       +
       

     

       197
       197
       +
       Most of the time, these are the same. For instance, the package `e2fsprogs` has a `pname` attribute `"e2fsprogs"`, is bound to the variable name `e2fsprogs` in `all-packages.nix`, and the Nix expression is in `pkgs/os-specific/linux/e2fsprogs/default.nix`.

     

       198
       198
       +
       

     

       199
       199
       +
       There are a few naming guidelines:

     

       200
       200
       +
       

     

       201
       201
       +
       - The `pname` attribute _should_ be identical to the upstream package name.

     

       202
       202
       +
       

     

       203
       203
       +
       - The `pname` and the `version` attribute _must not_ contain uppercase letters — e.g., `"mplayer" instead of `"MPlayer"`.

     

       204
       204
       +
       

     

       205
       205
       +
       - The `version` attribute _must_ start with a digit e.g`"0.3.1rc2".

     

       206
       206
       +
       

     

       207
       207
       +
       - If a package is a commit from a repository without a version assigned, then the `version` attribute _should_ be the latest upstream version preceding that commit, followed by `-unstable-` and the date of the (fetched) commit. The date _must_ be in `"YYYY-MM-DD"` format.

     

       208
       208
       +
       

     

       209
       209
       +
       Example: Given a project had its latest releases `2.2` in November 2021, and `3.0` in January 2022, a commit authored on March 15, 2022 for an upcoming bugfix release `2.2.1` would have `version = "2.2-unstable-2022-03-15"`.

     

       210
       210
       +
       

     

       211
       211
       +
       - Dashes in the package `pname` _should_ be preserved in new variable names, rather than converted to underscores or camel cased — e.g., `http-parser` instead of `http_parser` or `httpParser`. The hyphenated style is preferred in all three package names.

     

       212
       212
       +
       

     

       213
       213
       +
       - If there are multiple versions of a package, this _should_ be reflected in the variable names in `all-packages.nix`, e.g. `json-c_0_9` and `json-c_0_11`. If there is an obvious “default” version, make an attribute like `json-c = json-c_0_9;`. See also [](#sec-versioning)

     

       214
       214
       +
       

     

       215
       215
       +
       ### Versioning {#sec-versioning}

     

       216
       216
       +
       

     

       217
       217
       +
       Because every version of a package in Nixpkgs creates a potential maintenance burden, old versions of a package should not be kept unless there is a good reason to do so. For instance, Nixpkgs contains several versions of GCC because other packages don’t build with the latest version of GCC. Other examples are having both the latest stable and latest pre-release version of a package, or to keep several major releases of an application that differ significantly in functionality.

     

       218
       218
       +
       

     

       219
       219
       +
       If there is only one version of a package, its Nix expression should be named `e2fsprogs/default.nix`. If there are multiple versions, this should be reflected in the filename, e.g. `e2fsprogs/1.41.8.nix` and `e2fsprogs/1.41.9.nix`. The version in the filename should leave out unnecessary detail. For instance, if we keep the latest Firefox 2.0.x and 3.5.x versions in Nixpkgs, they should be named `firefox/2.0.nix` and `firefox/3.5.nix`, respectively (which, at a given point, might contain versions `2.0.0.20` and `3.5.4`). If a version requires many auxiliary files, you can use a subdirectory for each version, e.g. `firefox/2.0/default.nix` and `firefox/3.5/default.nix`.

     

       220
       220
       +
       

     

       221
       221
       +
       All versions of a package _must_ be included in `all-packages.nix` to make sure that they evaluate correctly.

     

       222
       222
       +
       

     

       223
       223
       +
       ### (Meta attributes)

     

       224
       224
       +
       

     

       5
       225
        
       * `meta.description` must:

     

       6
       226
        
         * Be short, just one sentence.

     

       7
       227
        
         * Be capitalized.

     
···

       17
       237
        
       

     

       18
       238
        
       See the nixpkgs manual for more details on [standard meta-attributes](https://nixos.org/nixpkgs/manual/#sec-standard-meta-attributes).

     

       19
       239
        
       

     

       20
       20
       -
       ## Testing changes

     

       240
       240
       +
       ### Import From Derivation {#ssec-import-from-derivation}

     

       241
       241
       +
       

     

       242
       242
       +
       Import From Derivation (IFD) is disallowed in Nixpkgs for performance reasons:

     

       243
       243
       +
       [Hydra] evaluates the entire package set, and sequential builds during evaluation would increase evaluation times to become impractical.

     

       244
       244
       +
       

     

       245
       245
       +
       [Hydra]: https://github.com/NixOS/hydra

     

       246
       246
       +
       

     

       247
       247
       +
       Import From Derivation can be worked around in some cases by committing generated intermediate files to version control and reading those instead.

     

       248
       248
       +
       

     

       249
       249
       +
       <!-- TODO: remove the following and link to Nix manual once https://github.com/NixOS/nix/pull/7332 is merged -->

     

       250
       250
       +
       

     

       251
       251
       +
       See also [NixOS Wiki: Import From Derivation].

     

       252
       252
       +
       

     

       253
       253
       +
       [NixOS Wiki: Import From Derivation]: https://nixos.wiki/wiki/Import_From_Derivation

     

       254
       254
       +
       

     

       255
       255
       +
       ## (Sources)

     

       256
       256
       +
       

     

       257
       257
       +
       ### Fetching Sources {#sec-sources}

     

       258
       258
       +
       

     

       259
       259
       +
       There are multiple ways to fetch a package source in nixpkgs. The general guideline is that you should package reproducible sources with a high degree of availability. Right now there is only one fetcher which has mirroring support and that is `fetchurl`. Note that you should also prefer protocols which have a corresponding proxy environment variable.

     

       260
       260
       +
       

     

       261
       261
       +
       You can find many source fetch helpers in `pkgs/build-support/fetch*`.

     

       262
       262
       +
       

     

       263
       263
       +
       In the file `pkgs/top-level/all-packages.nix` you can find fetch helpers, these have names on the form `fetchFrom*`. The intention of these are to provide snapshot fetches but using the same api as some of the version controlled fetchers from `pkgs/build-support/`. As an example going from bad to good:

     

       264
       264
       +
       

     

       265
       265
       +
       - Bad: Uses `git://` which won't be proxied.

     

       266
       266
       +
       

     

       267
       267
       +
         ```nix

     

       268
       268
       +
         src = fetchgit {

     

       269
       269
       +
           url = "git@github.com:NixOS/nix.git"

     

       270
       270
       +
           url = "git://github.com/NixOS/nix.git";

     

       271
       271
       +
           rev = "1f795f9f44607cc5bec70d1300150bfefcef2aae";

     

       272
       272
       +
           hash = "sha256-7D4m+saJjbSFP5hOwpQq2FGR2rr+psQMTcyb1ZvtXsQ=";

     

       273
       273
       +
         }

     

       274
       274
       +
         ```

     

       275
       275
       +
       

     

       276
       276
       +
       - Better: This is ok, but an archive fetch will still be faster.

     

       277
       277
       +
       

     

       278
       278
       +
         ```nix

     

       279
       279
       +
         src = fetchgit {

     

       280
       280
       +
           url = "https://github.com/NixOS/nix.git";

     

       281
       281
       +
           rev = "1f795f9f44607cc5bec70d1300150bfefcef2aae";

     

       282
       282
       +
           hash = "sha256-7D4m+saJjbSFP5hOwpQq2FGR2rr+psQMTcyb1ZvtXsQ=";

     

       283
       283
       +
         }

     

       284
       284
       +
         ```

     

       285
       285
       +
       

     

       286
       286
       +
       - Best: Fetches a snapshot archive and you get the rev you want.

     

       287
       287
       +
       

     

       288
       288
       +
         ```nix

     

       289
       289
       +
         src = fetchFromGitHub {

     

       290
       290
       +
           owner = "NixOS";

     

       291
       291
       +
           repo = "nix";

     

       292
       292
       +
           rev = "1f795f9f44607cc5bec70d1300150bfefcef2aae";

     

       293
       293
       +
           hash = "sha256-7D4m+saJjbSFP5hOwpQq2FGR2rr+psQMTcyb1ZvtXsQ=";

     

       294
       294
       +
         }

     

       295
       295
       +
         ```

     

       296
       296
       +
       

     

       297
       297
       +
       When fetching from GitHub, commits must always be referenced by their full commit hash. This is because GitHub shares commit hashes among all forks and returns `404 Not Found` when a short commit hash is ambiguous. It already happens for some short, 6-character commit hashes in `nixpkgs`.

     

       298
       298
       +
       It is a practical vector for a denial-of-service attack by pushing large amounts of auto generated commits into forks and was already [demonstrated against GitHub Actions Beta](https://blog.teddykatz.com/2019/11/12/github-actions-dos.html).

     

       299
       299
       +
       

     

       300
       300
       +
       Find the value to put as `hash` by running `nix-shell -p nix-prefetch-github --run "nix-prefetch-github --rev 1f795f9f44607cc5bec70d1300150bfefcef2aae NixOS nix"`.

     

       301
       301
       +
       

     

       302
       302
       +
       #### Obtaining source hash {#sec-source-hashes}

     

       303
       303
       +
       

     

       304
       304
       +
       Preferred source hash type is sha256. There are several ways to get it.

     

       305
       305
       +
       

     

       306
       306
       +
       1. Prefetch URL (with `nix-prefetch-XXX URL`, where `XXX` is one of `url`, `git`, `hg`, `cvs`, `bzr`, `svn`). Hash is printed to stdout.

     

       307
       307
       +
       

     

       308
       308
       +
       2. Prefetch by package source (with `nix-prefetch-url '<nixpkgs>' -A PACKAGE.src`, where `PACKAGE` is package attribute name). Hash is printed to stdout.

     

       309
       309
       +
       

     

       310
       310
       +
           This works well when you've upgraded existing package version and want to find out new hash, but is useless if package can't be accessed by attribute or package has multiple sources (`.srcs`, architecture-dependent sources, etc).

     

       311
       311
       +
       

     

       312
       312
       +
       3. Upstream provided hash: use it when upstream provides `sha256` or `sha512` (when upstream provides `md5`, don't use it, compute `sha256` instead).

     

       313
       313
       +
       

     

       314
       314
       +
           A little nuance is that `nix-prefetch-*` tools produce hash encoded with `base32`, but upstream usually provides hexadecimal (`base16`) encoding. Fetchers understand both formats. Nixpkgs does not standardize on any one format.

     

       315
       315
       +
       

     

       316
       316
       +
           You can convert between formats with nix-hash, for example:

     

       317
       317
       +
       

     

       318
       318
       +
           ```ShellSession

     

       319
       319
       +
           $ nix-hash --type sha256 --to-base32 HASH

     

       320
       320
       +
           ```

     

       321
       321
       +
       

     

       322
       322
       +
       4. Extracting hash from local source tarball can be done with `sha256sum`. Use `nix-prefetch-url file:///path/to/tarball` if you want base32 hash.

     

       323
       323
       +
       

     

       324
       324
       +
       5. Fake hash: set the hash to one of

     

       325
       325
       +
       

     

       326
       326
       +
          - `""`

     

       327
       327
       +
          - `lib.fakeHash`

     

       328
       328
       +
          - `lib.fakeSha256`

     

       329
       329
       +
          - `lib.fakeSha512`

     

       330
       330
       +
       

     

       331
       331
       +
          in the package expression, attempt build and extract correct hash from error messages.

     

       332
       332
       +
       

     

       333
       333
       +
          ::: {.warning}

     

       334
       334
       +
          You must use one of these four fake hashes and not some arbitrarily-chosen hash.

     

       335
       335
       +
       

     

       336
       336
       +
          See [](#sec-source-hashes-security).

     

       337
       337
       +
          :::

     

       338
       338
       +
       

     

       339
       339
       +
           This is last resort method when reconstructing source URL is non-trivial and `nix-prefetch-url -A` isn’t applicable (for example, [one of `kodi` dependencies](https://github.com/NixOS/nixpkgs/blob/d2ab091dd308b99e4912b805a5eb088dd536adb9/pkgs/applications/video/kodi/default.nix#L73)). The easiest way then would be replace hash with a fake one and rebuild. Nix build will fail and error message will contain desired hash.

     

       340
       340
       +
       

     

       341
       341
       +
       

     

       342
       342
       +
       #### Obtaining hashes securely {#sec-source-hashes-security}

     

       343
       343
       +
       

     

       344
       344
       +
       Let's say Man-in-the-Middle (MITM) sits close to your network. Then instead of fetching source you can fetch malware, and instead of source hash you get hash of malware. Here are security considerations for this scenario:

     

       345
       345
       +
       

     

       346
       346
       +
       - `http://` URLs are not secure to prefetch hash from;

     

       347
       347
       +
       

     

       348
       348
       +
       - hashes from upstream (in method 3) should be obtained via secure protocol;

     

       349
       349
       +
       

     

       350
       350
       +
       - `https://` URLs are secure in methods 1, 2, 3;

     

       351
       351
       +
       

     

       352
       352
       +
       - `https://` URLs are secure in method 5 *only if* you use one of the listed fake hashes. If you use any other hash, `fetchurl` will pass `--insecure` to `curl` and may then degrade to HTTP in case of TLS certificate expiration.

     

       353
       353
       +
       

     

       354
       354
       +
       ### Patches {#sec-patches}

     

       355
       355
       +
       

     

       356
       356
       +
       Patches available online should be retrieved using `fetchpatch`.

     

       357
       357
       +
       

     

       358
       358
       +
       ```nix

     

       359
       359
       +
       patches = [

     

       360
       360
       +
         (fetchpatch {

     

       361
       361
       +
           name = "fix-check-for-using-shared-freetype-lib.patch";

     

       362
       362
       +
           url = "http://git.ghostscript.com/?p=ghostpdl.git;a=patch;h=8f5d285";

     

       363
       363
       +
           hash = "sha256-uRcxaCjd+WAuGrXOmGfFeu79cUILwkRdBu48mwcBE7g=";

     

       364
       364
       +
         })

     

       365
       365
       +
       ];

     

       366
       366
       +
       ```

     

       367
       367
       +
       

     

       368
       368
       +
       Otherwise, you can add a `.patch` file to the `nixpkgs` repository. In the interest of keeping our maintenance burden to a minimum, only patches that are unique to `nixpkgs` should be added in this way.

     

       369
       369
       +
       

     

       370
       370
       +
       If a patch is available online but does not cleanly apply, it can be modified in some fixed ways by using additional optional arguments for `fetchpatch`. Check [](#fetchpatch) for details.

     

       371
       371
       +
       

     

       372
       372
       +
       ```nix

     

       373
       373
       +
       patches = [ ./0001-changes.patch ];

     

       374
       374
       +
       ```

     

       375
       375
       +
       

     

       376
       376
       +
       If you do need to do create this sort of patch file, one way to do so is with git:

     

       377
       377
       +
       

     

       378
       378
       +
       1. Move to the root directory of the source code you're patching.

     

       379
       379
       +
       

     

       380
       380
       +
           ```ShellSession

     

       381
       381
       +
           $ cd the/program/source

     

       382
       382
       +
           ```

     

       383
       383
       +
       

     

       384
       384
       +
       2. If a git repository is not already present, create one and stage all of the source files.

     

       385
       385
       +
       

     

       386
       386
       +
           ```ShellSession

     

       387
       387
       +
           $ git init

     

       388
       388
       +
           $ git add .

     

       389
       389
       +
           ```

     

       390
       390
       +
       

     

       391
       391
       +
       3. Edit some files to make whatever changes need to be included in the patch.

     

       392
       392
       +
       

     

       393
       393
       +
       4. Use git to create a diff, and pipe the output to a patch file:

     

       394
       394
       +
       

     

       395
       395
       +
           ```ShellSession

     

       396
       396
       +
           $ git diff -a > nixpkgs/pkgs/the/package/0001-changes.patch

     

       397
       397
       +
           ```

     

       398
       398
       +
       

     

       399
       399
       +
       ## Testing changes | Package tests {#sec-package-tests}

     

       21
       400
        
       

     

       22
       401
        
       To run the main types of tests locally:

     

       23
       402
        
       

     
···

       25
       404
        
       - Run [NixOS tests](https://nixos.org/manual/nixos/unstable/#sec-nixos-tests) with `nix-build --attr nixosTest.NAME`, where `NAME` is the name of the test listed in `nixos/tests/all-tests.nix`

     

       26
       405
        
       - Run [global package tests](https://nixos.org/manual/nixpkgs/unstable/#sec-package-tests) with `nix-build --attr tests.PACKAGE`, where `PACKAGE` is the name of the test listed in `pkgs/test/default.nix`

     

       27
       406
        
       - See `lib/tests/NAME.nix` for instructions on running specific library tests

     

       407
       407
       +
       

     

       408
       408
       +
       Tests are important to ensure quality and make reviews and automatic updates easy.

     

       409
       409
       +
       

     

       410
       410
       +
       The following types of tests exists:

     

       411
       411
       +
       

     

       412
       412
       +
       * [NixOS **module tests**](https://nixos.org/manual/nixos/stable/#sec-nixos-tests), which spawn one or more NixOS VMs. They exercise both NixOS modules and the packaged programs used within them. For example, a NixOS module test can start a web server VM running the `nginx` module, and a client VM running `curl` or a graphical `firefox`, and test that they can talk to each other and display the correct content.

     

       413
       413
       +
       * Nix **package tests** are a lightweight alternative to NixOS module tests. They should be used to create simple integration tests for packages, but cannot test NixOS services, and some programs with graphical user interfaces may also be difficult to test with them.

     

       414
       414
       +
       * The **`checkPhase` of a package**, which should execute the unit tests that are included in the source code of a package.

     

       415
       415
       +
       

     

       416
       416
       +
       Here in the nixpkgs manual we describe mostly _package tests_; for _module tests_ head over to the corresponding [section in the NixOS manual](https://nixos.org/manual/nixos/stable/#sec-nixos-tests).

     

       417
       417
       +
       

     

       418
       418
       +
       ### Writing inline package tests {#ssec-inline-package-tests-writing}

     

       419
       419
       +
       

     

       420
       420
       +
       For very simple tests, they can be written inline:

     

       421
       421
       +
       

     

       422
       422
       +
       ```nix

     

       423
       423
       +
       { …, yq-go }:

     

       424
       424
       +
       

     

       425
       425
       +
       buildGoModule rec {

     

       426
       426
       +
         …

     

       427
       427
       +
       

     

       428
       428
       +
         passthru.tests = {

     

       429
       429
       +
           simple = runCommand "${pname}-test" {} ''

     

       430
       430
       +
             echo "test: 1" | ${yq-go}/bin/yq eval -j > $out

     

       431
       431
       +
             [ "$(cat $out | tr -d $'\n ')" = '{"test":1}' ]

     

       432
       432
       +
           '';

     

       433
       433
       +
         };

     

       434
       434
       +
       }

     

       435
       435
       +
       ```

     

       436
       436
       +
       

     

       437
       437
       +
       ### Writing larger package tests {#ssec-package-tests-writing}

     

       438
       438
       +
       

     

       439
       439
       +
       This is an example using the `phoronix-test-suite` package with the current best practices.

     

       440
       440
       +
       

     

       441
       441
       +
       Add the tests in `passthru.tests` to the package definition like this:

     

       442
       442
       +
       

     

       443
       443
       +
       ```nix

     

       444
       444
       +
       { stdenv, lib, fetchurl, callPackage }:

     

       445
       445
       +
       

     

       446
       446
       +
       stdenv.mkDerivation {

     

       447
       447
       +
         …

     

       448
       448
       +
       

     

       449
       449
       +
         passthru.tests = {

     

       450
       450
       +
           simple-execution = callPackage ./tests.nix { };

     

       451
       451
       +
         };

     

       452
       452
       +
       

     

       453
       453
       +
         meta = { … };

     

       454
       454
       +
       }

     

       455
       455
       +
       ```

     

       456
       456
       +
       

     

       457
       457
       +
       Create `tests.nix` in the package directory:

     

       458
       458
       +
       

     

       459
       459
       +
       ```nix

     

       460
       460
       +
       { runCommand, phoronix-test-suite }:

     

       461
       461
       +
       

     

       462
       462
       +
       let

     

       463
       463
       +
         inherit (phoronix-test-suite) pname version;

     

       464
       464
       +
       in

     

       465
       465
       +
       

     

       466
       466
       +
       runCommand "${pname}-tests" { meta.timeout = 60; }

     

       467
       467
       +
         ''

     

       468
       468
       +
           # automatic initial setup to prevent interactive questions

     

       469
       469
       +
           ${phoronix-test-suite}/bin/phoronix-test-suite enterprise-setup >/dev/null

     

       470
       470
       +
           # get version of installed program and compare with package version

     

       471
       471
       +
           if [[ `${phoronix-test-suite}/bin/phoronix-test-suite version` != *"${version}"*  ]]; then

     

       472
       472
       +
             echo "Error: program version does not match package version"

     

       473
       473
       +
             exit 1

     

       474
       474
       +
           fi

     

       475
       475
       +
           # run dummy command

     

       476
       476
       +
           ${phoronix-test-suite}/bin/phoronix-test-suite dummy_module.dummy-command >/dev/null

     

       477
       477
       +
           # needed for Nix to register the command as successful

     

       478
       478
       +
           touch $out

     

       479
       479
       +
         ''

     

       480
       480
       +
       ```

     

       481
       481
       +
       

     

       482
       482
       +
       ### Running package tests {#ssec-package-tests-running}

     

       483
       483
       +
       

     

       484
       484
       +
       You can run these tests with:

     

       485
       485
       +
       

     

       486
       486
       +
       ```ShellSession

     

       487
       487
       +
       $ cd path/to/nixpkgs

     

       488
       488
       +
       $ nix-build -A phoronix-test-suite.tests

     

       489
       489
       +
       ```

     

       490
       490
       +
       

     

       491
       491
       +
       ### Examples of package tests {#ssec-package-tests-examples}

     

       492
       492
       +
       

     

       493
       493
       +
       Here are examples of package tests:

     

       494
       494
       +
       

     

       495
       495
       +
       - [Jasmin compile test](https://github.com/NixOS/nixpkgs/blob/master/pkgs/development/compilers/jasmin/test-assemble-hello-world/default.nix)

     

       496
       496
       +
       - [Lobster compile test](https://github.com/NixOS/nixpkgs/blob/master/pkgs/development/compilers/lobster/test-can-run-hello-world.nix)

     

       497
       497
       +
       - [Spacy annotation test](https://github.com/NixOS/nixpkgs/blob/master/pkgs/development/python-modules/spacy/annotation-test/default.nix)

     

       498
       498
       +
       - [Libtorch test](https://github.com/NixOS/nixpkgs/blob/master/pkgs/development/libraries/science/math/libtorch/test/default.nix)

     

       499
       499
       +
       - [Multiple tests for nanopb](https://github.com/NixOS/nixpkgs/blob/master/pkgs/development/libraries/nanopb/default.nix)

     

       500
       500
       +
       

     

       501
       501
       +
       ### Linking NixOS module tests to a package {#ssec-nixos-tests-linking}

     

       502
       502
       +
       

     

       503
       503
       +
       Like [package tests](#ssec-package-tests-writing) as shown above, [NixOS module tests](https://nixos.org/manual/nixos/stable/#sec-nixos-tests) can also be linked to a package, so that the tests can be easily run when changing the related package.

     

       504
       504
       +
       

     

       505
       505
       +
       For example, assuming we're packaging `nginx`, we can link its module test via `passthru.tests`:

     

       506
       506
       +
       

     

       507
       507
       +
       ```nix

     

       508
       508
       +
       { stdenv, lib, nixosTests }:

     

       509
       509
       +
       

     

       510
       510
       +
       stdenv.mkDerivation {

     

       511
       511
       +
         ...

     

       512
       512
       +
       

     

       513
       513
       +
         passthru.tests = {

     

       514
       514
       +
           nginx = nixosTests.nginx;

     

       515
       515
       +
         };

     

       516
       516
       +
       

     

       517
       517
       +
         ...

     

       518
       518
       +
       }

     

       519
       519
       +
       ```