From 59707975a39b0a444444df4eb6c2e6d19ff5e050 Mon Sep 17 00:00:00 2001 From: Eelco Dolstra Date: Sun, 30 Dec 2007 23:36:09 +0000 Subject: [PATCH] * Documented indented string literals. * Release notes. --- doc/manual/builtins.xml | 2 +- doc/manual/release-notes.xml | 160 +++++++++++++++++++------ doc/manual/writing-nix-expressions.xml | 74 +++++++++++- 3 files changed, 193 insertions(+), 43 deletions(-) diff --git a/doc/manual/builtins.xml b/doc/manual/builtins.xml index 4c8e3163b..3b6b80324 100644 --- a/doc/manual/builtins.xml +++ b/doc/manual/builtins.xml @@ -486,7 +486,7 @@ removeAttrs { x = 1; y = 2; z = 3; } ["a" "x" "z"] - builtins.substr + builtins.substring start len s diff --git a/doc/manual/release-notes.xml b/doc/manual/release-notes.xml index ef2905d8a..4f14a0c75 100644 --- a/doc/manual/release-notes.xml +++ b/doc/manual/release-notes.xml @@ -8,20 +8,31 @@ -
Release 0.11 (TBA) +
Release 0.11 (December 31, +2007) + +The most important improvement in Nix 0.11 is secure multi-user +support. It also features many usability improvements and language +extensions, many of them to support NixOS. Here is an (incomplete) +list: + - TODO: multi-user support. The old setuid method for - sharing a store between multiple users has been - removed. + Secure multi-user support. A single Nix store can + now be shared between multiple (possible untrusted) users. This is + an important feature for NixOS, where it allows non-root users to + install software. The old setuid method for sharing a store between + multiple users has been removed. Details for setting up a + multi-user store can be found in the manual. The new command nix-copy-closure gives you an easy and efficient way to exchange software between machines. It copies the missing parts of the closure of a set of - store path to or from a remote machine. + store path to or from a remote machine via + ssh. nix-prefetch-url now by default @@ -47,15 +58,21 @@ for booting Linux don’t have any dependencies. + - TODO: now using Berkeley DB 4.5. + Nix now uses Berkeley DB 4.5. The database is + upgraded automatically, but you should be careful not to use old + versions of Nix that still use Berkeley DB 4.4. - TODO: option in - nix-store --register-validity. + The new attribute @@ -65,61 +82,118 @@ populated with the closure of certain paths. - TODO: option , - configuration setting - build-max-silent-time. + The option + (corresponding to the configuration setting + build-max-silent-time) allows you to set a + timeout on builds — if a build produces no output on + stdout or stderr for the given + number of seconds, it is terminated. This is useful for recovering + automatically from builds that are stuck in an infinite + loop. - TODO: nix-env - . + nix-env + modifies the current generation of a profile so that it contains + exactly the specified derivation, and nothing else. For example, + nix-env -p /nix/var/nix/profiles/browser --set + firefox lets the profile named + browser contain just Firefox. - TODO: . + The new (in + nix-env, nix-instantiate and + nix-build) is like , except + that the value is a string. For example, --argstr system + i686-linux is equivalent to --arg system + \"i686-linux\"' (note that + prevents annoying quoting around shell arguments). - TODO: nix-env now maintains meta - info about installed packages in user environments. to show all meta info. + nix-env now maintains + meta-information about installed packages in profiles. The + meta-information is the contents of the meta + attribute of derivations, such as description or + homepage. The command nix-env -q --xml + --meta shows all meta-information. - TODO: nix-env - . Specific flags: - active, priority, - keep. + nix-env now uses the + meta.priority attribute of derivations to resolve + filename collisions between packages. Lower priority values denote + a higher priority. For instance, the GCC wrapper package and the + Binutils package in Nixpkgs both have a file + bin/ld, so previously if you tried to install + both you would get a collision. Now, on the other hand, the GCC + wrapper declares a higher priority than Binutils, so the former’s + bin/ld is symlinked in the user + environment. + + + nix-env --set-flag allows + meta attributes of installed packages to be modified. There are + several attributes that can be usefully modified, because they + affect nix-env behaviour or the user environment + build script: + + + + meta.priority can be changed + to resolve filename clashes (see above). + + meta.keep can be set to + true to prevent the package from being + upgraded or replaced. Useful if you want to hang on to an older + version of a package. (This is similar to masking in + Gentoo.) + + meta.active can be set to + false to “disable” the package. That is, no + symlinks will be generated to the files of the package, but it + remains part of the profile (so it won’t be garbage-collected). + Set it back to true to re-enable the + package. + + + + - TODO: nix-env - / take package priorities into - account. - - nix-env -q now has a flag () that causes nix-env to show only those derivations whose output is already in the Nix store or that can be substituted (i.e., downloaded from somewhere). In other words, it shows the packages that can be installed “quickly”, i.e., don’t need to be built from - source. TODO: flag is also available in nix-env -i / - -u. + source. The flag is also available in + nix-env -i and nix-env -u to + filter out derivations for which no pre-built binary is + available. - TODO: new built-ins + Several new built-in functions: builtins.attrNames, builtins.filterSource, - builtins.sub, + builtins.isAttrs, + builtins.isFunction, + builtins.listToAttrs, builtins.stringLength, - builtins.substring. + builtins.sub, + builtins.substring, + throw, + builtins.trace, + builtins.readFile. - TODO: each subscribed channel is its own attribute - in the top-level expression generated for the channel, this allows - disambiguation (nix-env -qaA). + nix-channel: each subscribed + channel is its own attribute in the top-level expression generated + for the channel. This allows disambiguation (e.g. nix-env + -i -A nixpkgs_unstable.firefox). The substitutes table has been removed from the database. This makes operations such as nix-pull - and nix-channel --update - much faster. + and nix-channel --update much, much + faster. nix-prefetch-url now has a @@ -128,11 +202,19 @@ the channel hasn’t changed. - TODO: chroot support. + Nix can now perform builds in an automatically + generated “chroot”. This prevents a builder from accessing stuff + outside of the Nix store, and thus helps ensure purity. This is an + experimental feature. - TODO: ''-style string - literals. + A new kind of string literal: strings between double + single-quotes ('') have indentation + “intelligently” removed. This allows large strings (such as shell + scripts or configuration file fragments in NixOS) to cleanly follow + the indentation of the surrounding expression. It also requires + much less escaping, since '' is less common in + most languages than ". diff --git a/doc/manual/writing-nix-expressions.xml b/doc/manual/writing-nix-expressions.xml index 54108e9cf..840eb120d 100644 --- a/doc/manual/writing-nix-expressions.xml +++ b/doc/manual/writing-nix-expressions.xml @@ -612,7 +612,10 @@ language. - Strings are enclosed between double + Strings can be written in three + ways. + + The most common way is to enclose the string between double quotes, e.g., "foo bar". Strings can span multiple lines. The special characters " and \ and the character sequence @@ -658,8 +661,73 @@ configureFlags = " some of which in turn contain expressions (e.g., ${mesa}). - As a convenience, URIs as defined in - appendix B of The second way to write string literals is as an + indented string, which is enclosed between + pairs of double single-quotes, like so: + + +'' + This is the first line. + This is the second line. + This is the third line. +'' + + This kind of string literal intelligently strips indentation from + the start of each line. To be precise, it strips from each line a + number of spaces equal to the minimal indentation of the string as + a whole (disregarding the indentation of empty lines). For + instance, the first and second line are indented two space, while + the third line is indented three spaces. Thus, two spaces are + stripped from each line, so the resulting string is + + +"This is the first line.\nThis is the second line.\n This is the third line.\n" + + + + Note that the whitespace and newline following the opening + '' is ignored if there is no non-whitespace + text on the initial line. + + Antiquotation + (${expr}}) is + supported in indented strings. + + Since ${ and '' have + special meaning in indented strings, you need a way to quote them. + ${ can be escaped by prefixing it with + '', i.e., ''${. + '' can be escaped by prefixing it with + ', i.e., '''. Finally, + linefeed, carriage-return and tab characters can be writted as + ''\n, ''\r, + ''\t. + + Indented strings are primarily useful in that they allow + multi-line string literals to follow the indentation of the + enclosing Nix expression, and that less escaping is typically + necessary for strings representing languages such as shell scripts + and configuration files because '' is much less + common than ". Example: + + +stdenv.mkDerivation { + ... + postInstall = + '' + mkdir $out/bin $out/etc + cp foo $out/bin + echo "Hello World" > $out/etc/foo.conf + ${if enableBar then "cp bar $out/bin" else ""} + ''; + ... +} + + + + + Finally, as a convenience, URIs as + defined in appendix B of RFC 2396 can be written as is, without quotes. For instance, the string