* Documented indented string literals.

* Release notes.
This commit is contained in:
Eelco Dolstra 2007-12-30 23:36:09 +00:00
parent de012e76e2
commit 59707975a3
3 changed files with 193 additions and 43 deletions

View file

@ -486,7 +486,7 @@ removeAttrs { x = 1; y = 2; z = 3; } ["a" "x" "z"]</screen>
</varlistentry> </varlistentry>
<varlistentry><term><function>builtins.substr</function> <varlistentry><term><function>builtins.substring</function>
<replaceable>start</replaceable> <replaceable>len</replaceable> <replaceable>start</replaceable> <replaceable>len</replaceable>
<replaceable>s</replaceable></term> <replaceable>s</replaceable></term>

View file

@ -8,20 +8,31 @@
<!--==================================================================--> <!--==================================================================-->
<section xml:id="ssec-relnotes-0.11"><title>Release 0.11 (TBA)</title> <section xml:id="ssec-relnotes-0.11"><title>Release 0.11 (December 31,
2007)</title>
<para>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:</para>
<itemizedlist> <itemizedlist>
<listitem><para>TODO: multi-user support. The old setuid method for <listitem><para>Secure multi-user support. A single Nix store can
sharing a store between multiple users has been now be shared between multiple (possible untrusted) users. This is
removed.</para></listitem> 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.</para></listitem>
<listitem><para>The new command <command>nix-copy-closure</command> <listitem><para>The new command <command>nix-copy-closure</command>
gives you an easy and efficient way to exchange software between gives you an easy and efficient way to exchange software between
machines. It copies the missing parts of the closure of a set of machines. It copies the missing parts of the closure of a set of
store path to or from a remote machine.</para></listitem> store path to or from a remote machine via
<command>ssh</command>.</para></listitem>
<listitem><para><command>nix-prefetch-url</command> now by default <listitem><para><command>nix-prefetch-url</command> now by default
@ -47,15 +58,21 @@
for booting Linux dont have any dependencies.</para></listitem> for booting Linux dont have any dependencies.</para></listitem>
<!--
<listitem><para>TODO: semantic cleanups of string concatenation <listitem><para>TODO: semantic cleanups of string concatenation
etc. (mostly in r6740).</para></listitem> etc. (mostly in r6740).</para></listitem>
-->
<listitem><para>TODO: now using Berkeley DB 4.5.</para></listitem> <listitem><para>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.</para></listitem>
<listitem><para>TODO: option <option>--reregister</option> in <!-- foo
<command>nix-store --register-validity</command>.</para></listitem> <listitem><para>TODO: option <option>- -reregister</option> in
<command>nix-store - -register-validity</command>.</para></listitem>
-->
<listitem><para>The new attribute <listitem><para>The new attribute
@ -65,32 +82,80 @@
populated with the closure of certain paths.</para></listitem> populated with the closure of certain paths.</para></listitem>
<listitem><para>TODO: option <option>--max-silent-time</option>, <listitem><para>The option <option>--max-silent-time</option>
configuration setting (corresponding to the configuration setting
<literal>build-max-silent-time</literal>.</para></listitem> <literal>build-max-silent-time</literal>) allows you to set a
timeout on builds — if a build produces no output on
<literal>stdout</literal> or <literal>stderr</literal> for the given
number of seconds, it is terminated. This is useful for recovering
automatically from builds that are stuck in an infinite
loop.</para></listitem>
<listitem><para>TODO: <command>nix-env</command> <listitem><para><command>nix-env</command> <option>--set</option>
<option>--set</option>.</para></listitem> modifies the current generation of a profile so that it contains
exactly the specified derivation, and nothing else. For example,
<literal>nix-env -p /nix/var/nix/profiles/browser --set
firefox</literal> lets the profile named
<filename>browser</filename> contain just Firefox.</para></listitem>
<listitem><para>TODO: <option>--argstr</option>.</para></listitem> <listitem><para>The new <option>--argstr</option> (in
<command>nix-env</command>, <command>nix-instantiate</command> and
<command>nix-build</command>) is like <option>--arg</option>, except
that the value is a string. For example, <literal>--argstr system
i686-linux</literal> is equivalent to <literal>--arg system
\"i686-linux\"'</literal> (note that <option>--argstr</option>
prevents annoying quoting around shell arguments).</para></listitem>
<listitem><para>TODO: <command>nix-env</command> now maintains meta <listitem><para><command>nix-env</command> now maintains
info about installed packages in user environments. <option>-q meta-information about installed packages in profiles. The
--xml --meta</option> to show all meta info.</para></listitem> meta-information is the contents of the <varname>meta</varname>
attribute of derivations, such as <varname>description</varname> or
<varname>homepage</varname>. The command <literal>nix-env -q --xml
--meta</literal> shows all meta-information.</para></listitem>
<listitem><para>TODO: <command>nix-env</command> <listitem><para><command>nix-env</command> now uses the
<option>--set-flag</option>. Specific flags: <varname>meta.priority</varname> attribute of derivations to resolve
<literal>active</literal>, <literal>priority</literal>, filename collisions between packages. Lower priority values denote
<literal>keep</literal>.</para></listitem> a higher priority. For instance, the GCC wrapper package and the
Binutils package in Nixpkgs both have a file
<filename>bin/ld</filename>, 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 formers
<filename>bin/ld</filename> is symlinked in the user
environment.</para></listitem>
<listitem><para>TODO: <command>nix-env</command> <option>-i</option> <listitem><para><command>nix-env --set-flag</command> allows
/ <option>-u</option> take package priorities into meta attributes of installed packages to be modified. There are
account.</para></listitem> several attributes that can be usefully modified, because they
affect <command>nix-env</command> behaviour or the user environment
build script:
<itemizedlist>
<listitem><para><varname>meta.priority</varname> can be changed
to resolve filename clashes (see above).</para></listitem>
<listitem><para><varname>meta.keep</varname> can be set to
<literal>true</literal> 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.)</para></listitem>
<listitem><para><varname>meta.active</varname> can be set to
<literal>false</literal> 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 wont be garbage-collected).
Set it back to <literal>true</literal> to re-enable the
package.</para></listitem>
</itemizedlist>
</para></listitem>
<listitem><para><command>nix-env -q</command> now has a flag <listitem><para><command>nix-env -q</command> now has a flag
@ -99,27 +164,36 @@
output is already in the Nix store or that can be substituted (i.e., output is already in the Nix store or that can be substituted (i.e.,
downloaded from somewhere). In other words, it shows the packages downloaded from somewhere). In other words, it shows the packages
that can be installed “quickly”, i.e., dont need to be built from that can be installed “quickly”, i.e., dont need to be built from
source. TODO: flag is also available in nix-env -i / source. The <option>-b</option> flag is also available in
-u.</para></listitem> <command>nix-env -i</command> and <command>nix-env -u</command> to
filter out derivations for which no pre-built binary is
available.</para></listitem>
<listitem><para>TODO: new built-ins <listitem><para>Several new built-in functions:
<function>builtins.attrNames</function>, <function>builtins.attrNames</function>,
<function>builtins.filterSource</function>, <function>builtins.filterSource</function>,
<function>builtins.sub</function>, <function>builtins.isAttrs</function>,
<function>builtins.isFunction</function>,
<function>builtins.listToAttrs</function>,
<function>builtins.stringLength</function>, <function>builtins.stringLength</function>,
<function>builtins.substring</function>.</para></listitem> <function>builtins.sub</function>,
<function>builtins.substring</function>,
<function>throw</function>,
<function>builtins.trace</function>,
<function>builtins.readFile</function>.</para></listitem>
<listitem><para>TODO: each subscribed channel is its own attribute <listitem><para><command>nix-channel</command>: each subscribed
in the top-level expression generated for the channel, this allows channel is its own attribute in the top-level expression generated
disambiguation (<command>nix-env -qaA</command>).</para></listitem> for the channel. This allows disambiguation (e.g. <literal>nix-env
-i -A nixpkgs_unstable.firefox</literal>).</para></listitem>
<listitem><para>The substitutes table has been removed from the <listitem><para>The substitutes table has been removed from the
database. This makes operations such as <command>nix-pull</command> database. This makes operations such as <command>nix-pull</command>
and <command>nix-channel --update</command> and <command>nix-channel --update</command> much, much
<emphasis>much</emphasis> faster.</para></listitem> faster.</para></listitem>
<listitem><para><command>nix-prefetch-url</command> now has a <listitem><para><command>nix-prefetch-url</command> now has a
@ -128,11 +202,19 @@
the channel hasnt changed.</para></listitem> the channel hasnt changed.</para></listitem>
<listitem><para>TODO: chroot support.</para></listitem> <listitem><para>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.</para></listitem>
<listitem><para>TODO: <literal>''</literal>-style string <listitem><para>A new kind of string literal: strings between double
literals.</para></listitem> single-quotes (<literal>''</literal>) 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 <literal>''</literal> is less common in
most languages than <literal>"</literal>.</para></listitem>
</itemizedlist> </itemizedlist>

View file

@ -612,7 +612,10 @@ language.</para>
<listitem> <listitem>
<para><emphasis>Strings</emphasis> are enclosed between double <para><emphasis>Strings</emphasis> can be written in three
ways.</para>
<para>The most common way is to enclose the string between double
quotes, e.g., <literal>"foo bar"</literal>. Strings can span quotes, e.g., <literal>"foo bar"</literal>. Strings can span
multiple lines. The special characters <literal>"</literal> and multiple lines. The special characters <literal>"</literal> and
<literal>\</literal> and the character sequence <literal>\</literal> and the character sequence
@ -658,8 +661,73 @@ configureFlags = "
some of which in turn contain expressions (e.g., some of which in turn contain expressions (e.g.,
<literal>${mesa}</literal>).</para> <literal>${mesa}</literal>).</para>
<para>As a convenience, <emphasis>URIs</emphasis> as defined in <para>The second way to write string literals is as an
appendix B of <link <emphasis>indented string</emphasis>, which is enclosed between
pairs of <emphasis>double single-quotes</emphasis>, like so:
<programlisting>
''
This is the first line.
This is the second line.
This is the third line.
''</programlisting>
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
<programlisting>
"This is the first line.\nThis is the second line.\n This is the third line.\n"</programlisting>
</para>
<para>Note that the whitespace and newline following the opening
<literal>''</literal> is ignored if there is no non-whitespace
text on the initial line.</para>
<para>Antiquotation
(<literal>${<replaceable>expr</replaceable>}}</literal>) is
supported in indented strings.</para>
<para>Since <literal>${</literal> and <literal>''</literal> have
special meaning in indented strings, you need a way to quote them.
<literal>${</literal> can be escaped by prefixing it with
<literal>''</literal>, i.e., <literal>''${</literal>.
<literal>''</literal> can be escaped by prefixing it with
<literal>'</literal>, i.e., <literal>'''</literal>. Finally,
linefeed, carriage-return and tab characters can be writted as
<literal>''\n</literal>, <literal>''\r</literal>,
<literal>''\t</literal>.</para>
<para>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 <literal>''</literal> is much less
common than <literal>"</literal>. Example:
<programlisting>
stdenv.mkDerivation {
<replaceable>...</replaceable>
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 ""}
'';
<replaceable>...</replaceable>
}
</programlisting>
</para>
<para>Finally, as a convenience, <emphasis>URIs</emphasis> as
defined in appendix B of <link
xlink:href='http://www.ietf.org/rfc/rfc2396.txt'>RFC 2396</link> xlink:href='http://www.ietf.org/rfc/rfc2396.txt'>RFC 2396</link>
can be written <emphasis>as is</emphasis>, without quotes. For can be written <emphasis>as is</emphasis>, without quotes. For
instance, the string instance, the string