Commit graph

67 commits

Author SHA1 Message Date
Ryan Mulligan 606bf6dc17 doc/functions/generators: convert to CommonMark 2021-06-11 06:06:42 -07:00
Ryan Mulligan c682532fce doc/functions/prefer-remote-fetch: convert to CommonMark 2021-06-07 20:18:39 -07:00
Ryan Mulligan fbfdc8fc0b doc/functions/debug: convert to CommonMark 2021-06-07 19:56:38 -07:00
Antoine Martin 26ac257e4f doc: nix-gitignore to CommonMark
Closes #125670
2021-06-05 18:20:26 +02:00
Frederik Rietdijk 2b9713c281 doc: move fhs and mkShell under builders/special
In my opinion Functions should only contain pure functions. These are
both meant to provide derivations so I put them under Builders. Don't
know exactly *where* to put them so "special" it is...
2019-10-21 11:39:46 +02:00
Frederik Rietdijk 24b1ef5133 doc: move overrides into separate chapter 2019-10-21 11:19:46 +02:00
Frederik Rietdijk 9d54ea9b2d doc: move image builders into new images chapter 2019-10-21 10:57:56 +02:00
Frederik Rietdijk 16d733bbe5 doc: move fetchers and trivial builders under builders 2019-10-20 13:35:04 +02:00
Jan Tojnar 83c2ad80ca
doc: re-format 2019-09-18 22:12:54 +02:00
Katharina Fey 18f7f19ce2 ociTools: init 2019-09-04 22:46:42 +00:00
Graham Christensen a82901fb5e
snapTools.makeSnap: init 2019-06-18 18:51:58 +02:00
Graham Christensen 695fb802f1
Merge pull request #54693 from tilpner/appimage-tools
appimageTools: init
2019-02-23 18:06:31 -05:00
tilpner 58443d8a50
appimageTools: init
The appimageTools attrset contains utilities to prevent
the usage of appimage-run to package AppImages, like done/attempted
in #49370 and #53156.

This has the advantage of allowing for per-package environment changes,
and extracts into the store instead of the users home directory.

The package list was extracted into appimageTools to prevent
duplication.
2019-02-23 21:04:21 +01:00
Raitis Veinbahs d8a7a01fec nix-gitignore: init at v3.0.0 (#46112)
closes siers/nix-gitignore#6
2019-02-18 09:57:30 +00:00
Matthew Bauer 498a242bf4 nixpkgs/manual: add trivial builders section
Fixes #25507.
2019-01-26 22:48:47 -05:00
Matthew Bauer 17ec7f3a16 nixpkgs/manual: document fetcher functions
Fixes #32439.
2019-01-26 22:48:47 -05:00
Jörg Thalheim eac6797380
prefer-fetch-remote: an overlay to fetch on remote builders
This is useful when running tools like NixOps or nix-review
on workstations where the upload to the builder is significantly
slower then downloading the source on the builder itself.
2019-01-18 14:41:10 +00:00
Graham Christensen f835f77e02
nixpkgs: Start documenting library functions in XML
Covers assert functions and about half of the attrsets functions.

Some internal consistency around IDs could be improved.
2018-10-05 10:06:08 -04:00
Graham Christensen c3125498fd
shell functions: rewrite as xml 2018-10-02 14:16:27 -04:00
Graham Christensen 507a63c885
nixpkgs docs: move shell section to its own file 2018-10-02 14:13:42 -04:00
Graham Christensen 8bf342ffb8
nixpkgs docs: move dockertool to its own file 2018-10-02 14:13:12 -04:00
Graham Christensen 0856d5c4ad
nixpkgs docs: move fhs-environments to its own file 2018-10-02 14:08:36 -04:00
Graham Christensen 3ac79c89b7
nixpkgs docs: move debug to its own file 2018-10-02 14:07:06 -04:00
Graham Christensen 9ae39b3553
nixpkgs docs: move generators to its own file 2018-10-02 14:03:59 -04:00
Graham Christensen f200a322c4
nixpkgs docs: move overrides to its own file 2018-10-02 13:52:21 -04:00
Graham Christensen d1e46df24b fixup: drop comment about config behaving differently from buildImage 2018-09-27 08:14:04 -04:00
Graham Christensen 4fe9006190 dockerTools.buildLayeredImage: init
Create a many-layered Docker Image.

Implements much less than buildImage:

 - Doesn't support specific uids/gids
 - Doesn't support runninng commands after building
 - Doesn't require qemu
 - Doesn't create mutable copies of the files in the path
 - Doesn't support parent images

If you want those feature, I recommend using buildLayeredImage as an
input to buildImage.

Notably, it does support:

 - Caching low level, common paths based on a graph traversial
   algorithm, see referencesByPopularity in
   0a80233487993256e811f566b1c80a40394c03d6
 - Configurable number of layers. If you're not using AUFS or not
   extending the image, you can specify a larger number of layers at
   build time:

       pkgs.dockerTools.buildLayeredImage {
         name = "hello";
         maxLayers = 128;
         config.Cmd = [ "${pkgs.gitFull}/bin/git" ];
       };

 - Parallelized creation of the layers, improving build speed.
 - The contents of the image includes the closure of the configuration,
   so you don't have to specify paths in contents and config.

   With buildImage, paths referred to by the config were not included
   automatically in the image. Thus, if you wanted to call Git, you
   had to specify it twice:

       pkgs.dockerTools.buildImage {
         name = "hello";
         contents = [ pkgs.gitFull ];
         config.Cmd = [ "${pkgs.gitFull}/bin/git" ];
       };

   buildLayeredImage on the other hand includes the runtime closure of
   the config when calculating the contents of the image:

       pkgs.dockerTools.buildImage {
         name = "hello";
         config.Cmd = [ "${pkgs.gitFull}/bin/git" ];
       };

Minor Problems

 - If any of the store paths change, every layer will be rebuilt in
   the nix-build. However, beacuse the layers are bit-for-bit
   reproducable, when these images are loaded in to Docker they will
   match existing layers and not be imported or uploaded twice.

Common Questions

 - Aren't Docker layers ordered?

   No. People who have used a Dockerfile before assume Docker's
   Layers are inherently ordered. However, this is not true -- Docker
   layers are content-addressable and are not explicitly layered until
   they are composed in to an Image.

 - What happens if I have more than maxLayers of store paths?

   The first (maxLayers-2) most "popular" paths will have their own
   individual layers, then layer #(maxLayers-1) will contain all the
   remaining "unpopular" paths, and finally layer #(maxLayers) will
   contain the Image configuration.
2018-09-26 17:54:14 -04:00
Graham Christensen 7736337916
Clarfy the binary reproducibility problems of created=now with dockerTools.buildImage. 2018-09-20 20:23:04 -04:00
Graham Christensen a32d7e0c74 dockerTools.buildImage: support impure dates
Because dates are an impurity, by default buildImage will use a static
date of one second past the UNIX Epoch. This can be a bit frustrating
when listing docker images in the CLI:

    $ docker image list
    REPOSITORY   TAG      IMAGE ID       CREATED        SIZE
    hello        latest   08c791c7846e   48 years ago   25.2MB

If you want to trade the purity for a better user experience, you can
set created to now.

    pkgs.dockerTools.buildImage {
      name = "hello";
      tag = "latest";
      created = "now";
      contents = pkgs.hello;

      config.Cmd = [ "/bin/hello" ];
    }

and now the Docker CLI will display a reasonable date and sort the
images as expected:

    $ docker image list
    REPOSITORY   TAG      IMAGE ID       CREATED              SIZE
    hello        latest   de2bf4786de6   About a minute ago   25.2MB
2018-09-20 18:26:02 +02:00
Eelco Dolstra eac06ed070
Manual: Random indentation fixes 2018-09-03 17:13:46 +02:00
Graham Christensen 360f420ac7
nixpkgs docs: normalize 2018-08-27 19:54:41 -04:00
Graham Christensen 53371b15c6
docs: include shell section 2018-08-27 19:53:25 -04:00
Nick Novitski c58b11d229 dockerTools.pullImage: control OS and architecture 2018-07-27 12:29:31 -07:00
Mathias Schreck 39e678e24e dockerTools.buildImage: add option to use nix output hash as tag 2018-07-06 15:15:09 +02:00
Samuel Dionne-Riel a45edd9024 doc: ran make format
With visual inspection that nothing got worse.
2018-05-31 21:03:37 -04:00
Antoine Eiche d35dcb1280 dockerTools.pullImage: documentation and release note 2018-05-02 21:32:20 +02:00
Graham Christensen 77161de454
nixpkgs docs: format =) 2018-05-01 19:54:21 -04:00
Profpatsch 21b87a7bdb docs: initial manual entry for lib/debug.nix
It is more of a stub for now, but at least points to the right file.
2018-04-27 18:59:39 +02:00
Profpatsch e01d485ce4 lib/generators: add an example of overriding defaults
An example of overriding the `toINI` generator is added,
hopefully clarifying the expressiveness of generators.
2018-03-29 16:53:06 +02:00
Mathias Schreck cd3d852943 dockerTools: document image spec v1.2 compatibility 2017-08-03 11:52:03 +02:00
Jan Tojnar e35f3c0679
doc: Fix some typos 2017-06-11 22:13:42 +02:00
Jörg Thalheim 36fca93290
rename iana_etc to iana-etc
fixes #23621
2017-03-28 22:35:15 +02:00
Paul Kinsky b14dd0e6c3
wrap added notes in <note> 2017-02-20 22:25:32 -05:00
Paul Kinsky 2d78767973
Add tips for resolving https issues in containers
I ran into some issues making HTTPS requests from a container built with buildImage. I've added notes with tips for resolving similar issues.
2017-02-20 22:24:54 -05:00
Eelco Dolstra 9d6a55aefd
~/.nixpkgs -> ~/.config/nixpkgs
The former is still respected as a fallback for config.nix for
backwards compatibility (but not for overlays because they're a new
feature).
2017-02-01 16:07:55 +01:00
Nicolas B. Pierron f5dfe78a1e Add overlays mechanism to Nixpkgs.
This patch add a new argument to Nixpkgs default expression named "overlays".

By default, the value of the argument is either taken from the environment variable `NIXPKGS_OVERLAYS`,
or from the directory `~/.nixpkgs/overlays/`.  If the environment variable does not name a valid directory
then this mechanism would fallback on the home directory.  If the home directory does not exists it will
fallback on an empty list of overlays.

The overlays directory should contain the list of extra Nixpkgs stages which would be used to extend the
content of Nixpkgs, with additional set of packages.  The overlays, i-e directory, files, symbolic links
are used in alphabetical order.

The simplest overlay which extends Nixpkgs with nothing looks like:

```nix
self: super: {
}
```

More refined overlays can use `super` as the basis for building new packages, and `self` as a way to query
the final result of the fix-point.

An example of overlay which extends Nixpkgs with a small set of packages can be found at:
  https://github.com/nbp/nixpkgs-mozilla/blob/nixpkgs-overlay/moz-overlay.nix

To use this file, checkout the repository and add a symbolic link to
the `moz-overlay.nix` file in `~/.nixpkgs/overlays` directory.
2017-01-16 01:17:33 +01:00
Kier Davis cb4ebb6749
docs: fix a couple of unmatched parentheses 2017-01-12 21:04:20 +00:00
Profpatsch 53fc7b8272 lib/generators: add manual documentation
Restructures the functions reference a bit.
2016-11-17 23:19:28 +01:00
Domen Kožar 62edf873aa Merge pull request #18660 from aneeshusa/add-override-attrs
mkDerivation: add overrideAttrs function
2016-10-30 11:32:15 +01:00
Joachim Fasting a1ecc5648a
nixpkgs doc: fix build
Ref e4cd45a30c
2016-10-28 16:28:31 +02:00