From 0bbbdfbc528e5b0f6fe0870304314a393923e02d Mon Sep 17 00:00:00 2001 From: Matthew Bauer Date: Sat, 20 May 2017 22:25:05 -0500 Subject: [PATCH] manual: add "declarative package management" section MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit This section gives some details on how to setup an "environment" without having to go through NixOS (although it could be used there too). I’ve tried to make it straightforward and have a kind of "tutorial" feel. Not sure if that’s appropriate for the manual, so any recommended changes would be helpful. --- doc/configuration.xml | 213 ++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 213 insertions(+) diff --git a/doc/configuration.xml b/doc/configuration.xml index 56950e07ab5c..361d23f7c656 100644 --- a/doc/configuration.xml +++ b/doc/configuration.xml @@ -243,5 +243,218 @@ set of packages. +
+ Declarative Package Management + +
+ Build an environment + + + Using packageOverrides, it is possible to manage + packages declaratively. This means that we can list all of our desired + packages within a declarative Nix expression. For example, to have + aspell, bc, + ffmpeg, coreutils, + gdb, nixUnstable, + emscripten, jq, + nox, and silver-searcher, we could + use the following in ~/.config/nixpkgs/config.nix: + + + +{ + packageOverrides = pkgs: with pkgs; { + myPackages = pkgs.buildEnv { + name = "my-packages"; + paths = [ aspell bc coreutils gdb ffmpeg nixUnstable emscripten jq nox silver-searcher ]; + }; + }; +} + + + + To install it into our environment, you can just run nix-env -iA + nixpkgs.myPackages. If you want to load the packages to be built + from a working copy of nixpkgs you just run + nix-env -f. -iA myPackages. To explore what's been + installed, just look through ~/.nix-profile/. You can + see that a lot of stuff has been installed. Some of this stuff is useful + some of it isn't. Let's tell Nixpkgs to only link the stuff that we want: + + + +{ + packageOverrides = pkgs: with pkgs; { + myPackages = pkgs.buildEnv { + name = "my-packages"; + paths = [ aspell bc coreutils gdb ffmpeg nixUnstable emscripten jq nox silver-searcher ]; + pathsToLink = [ "/share" "/bin" ]; + }; + }; +} + + + + pathsToLink tells Nixpkgs to only link the paths listed + which gets rid of the extra stuff in the profile. + /bin and /share are good + defaults for a user environment, getting rid of the clutter. If you are + running on Nix on MacOS, you may want to add another path as well, + /Applications, that makes GUI apps available. + + +
+ +
+ Getting documentation + + + After building that new environment, look through + ~/.nix-profile to make sure everything is there that + we wanted. Discerning readers will note that some files are missing. Look + inside ~/.nix-profile/share/man/man1/ to verify this. + There are no man pages for any of the Nix tools! This is because some + packages like Nix have multiple outputs for things like documentation (see + section 4). Let's make Nix install those as well. + + + +{ + packageOverrides = pkgs: with pkgs; { + myPackages = pkgs.buildEnv { + name = "my-packages"; + paths = [ aspell bc coreutils ffmpeg nixUnstable emscripten jq nox silver-searcher ]; + pathsToLink = [ "/share/man" "/share/doc" /bin" ]; + extraOutputsToInstall = [ "man" "doc" ]; + }; + }; +} + + + + This provides us with some useful documentation for using our packages. + However, if we actually want those manpages to be detected by man, we need + to set up our environment. This can also be managed within Nix + expressions. + + + +{ + packageOverrides = pkgs: with pkgs; rec { + myProfile = writeText "my-profile" '' +export PATH=$HOME/.nix-profile/bin:/nix/var/nix/profiles/default/bin:/sbin:/bin:/usr/sbin:/usr/bin +export MANPATH=$HOME/.nix-profile/share/man:/nix/var/nix/profiles/default/share/man:/usr/share/man + ''; + myPackages = pkgs.buildEnv { + name = "my-packages"; + paths = [ + (runCommand "profile" {} '' +mkdir -p $out/etc/profile.d +cp ${myProfile} $out/etc/profile.d/my-profile.sh + '') + aspell + bc + coreutils + ffmpeg + man + nixUnstable + emscripten + jq + nox + silver-searcher + ]; + pathsToLink = [ "/share/man" "/share/doc" /bin" "/etc" ]; + extraOutputsToInstall = [ "man" "doc" ]; + }; + }; +} + + + + For this to work fully, you must also have this script sourced when you + are logged in. Try adding something like this to your + ~/.profile file: + + + +#!/bin/sh +if [ -d $HOME/.nix-profile/etc/profile.d ]; then + for i in $HOME/.nix-profile/etc/profile.d/*.sh; do + if [ -r $i ]; then + . $i + fi + done +fi + + + + Now just run source $HOME/.profile and you can starting + loading man pages from your environent. + + +
+ +
+ GNU info setup + + + Configuring GNU info is a little bit trickier than man pages. To work + correctly, info needs a database to be generated. This can be done with + some small modifications to our environment scripts. + + + +{ + packageOverrides = pkgs: with pkgs; rec { + myProfile = writeText "my-profile" '' +export PATH=$HOME/.nix-profile/bin:/nix/var/nix/profiles/default/bin:/sbin:/bin:/usr/sbin:/usr/bin +export MANPATH=$HOME/.nix-profile/share/man:/nix/var/nix/profiles/default/share/man:/usr/share/man +export INFOPATH=$HOME/.nix-profile/share/info:/nix/var/nix/profiles/default/share/info:/usr/share/info + ''; + myPackages = pkgs.buildEnv { + name = "my-packages"; + paths = [ + (runCommand "profile" {} '' +mkdir -p $out/etc/profile.d +cp ${myProfile} $out/etc/profile.d/my-profile.sh + '') + aspell + bc + coreutils + ffmpeg + man + nixUnstable + emscripten + jq + nox + silver-searcher + texinfoInteractive + ]; + pathsToLink = [ "/share/man" "/share/doc" "/share/info" "/bin" "/etc" ]; + extraOutputsToInstall = [ "man" "doc" "info" ]; + postBuild = '' + if [ -x $out/bin/install-info -a -w $out/share/info ]; then + shopt -s nullglob + for i in $out/share/info/*.info $out/share/info/*.info.gz; do + $out/bin/install-info $i $out/share/info/dir + done + fi + ''; + }; + }; +} + + + + postBuild tells Nixpkgs to run a command after building + the environment. In this case, install-info adds the + installed info pages to dir which is GNU info's default + root node. Note that texinfoInteractive is added to the + environment to give the install-info command. + + +
+ +