* Moved the coding conventions from maintainers/docs to the Nixpkgs

manual.
* Removed some out-dated files from maintainers/docs.

svn path=/nixpkgs/trunk/; revision=17419

doc/coding-conventions.xml

@@ -0,0 +1,175 @@
+<chapter xmlns="http://docbook.org/ns/docbook"
+         xmlns:xlink="http://www.w3.org/1999/xlink"
+         xml:id="chap-conventions">
+
+<title>Coding conventions</title>
+
+
+<section><title>Syntax</title>
+
+<itemizedlist>
+
+  <listitem><para>Use 2 spaces of indentation per indentation level in
+  Nix expressions, 4 spaces in shell scripts.</para></listitem>
+
+  <listitem><para>Do not use tab characters, i.e. configure your
+  editor to use soft tabs.  For instance, use <literal>(setq-default
+  indent-tabs-mode nil)</literal> in Emacs.  Everybody has different
+  tab settings so it’s asking for trouble.</para></listitem>
+
+  <listitem><para>Use <literal>lowerCamelCase</literal> for variable
+  names, not <literal>UpperCamelCase</literal>.  TODO: naming of
+  attributes in
+  <filename>all-packages.nix</filename>?</para></listitem>
+
+  <listitem><para>Function calls with attribute set arguments are
+  written as
+
+<programlisting>
+foo {
+  arg = ...;
+}
+</programlisting>
+
+  not
+
+<programlisting>
+foo
+{
+  arg = ...;
+}
+</programlisting>
+
+  Also fine is
+
+<programlisting>
+foo { arg = ...; }
+</programlisting>
+
+  if it's a short call.</para></listitem>
+
+  <listitem><para>In attribute sets or lists that span multiple lines,
+  the attribute names or list elements should be aligned:
+
+<programlisting>
+# A long list.
+list =
+  [ elem1
+    elem2
+    elem3
+  ];
+
+# A long attribute set.
+attrs =
+  { attr1 = short_expr;
+    attr2 =
+      if true then big_expr else big_expr;
+  };
+
+# Alternatively:
+attrs = {
+  attr1 = short_expr;
+  attr2 =
+    if true then big_expr else big_expr;
+};
+</programlisting>
+
+  </para></listitem>
+
+  <listitem><para>Short lists or attribute sets can be written on one
+  line:
+
+<programlisting>
+# A short list.
+list = [ elem1 elem2 elem3 ];
+
+# A short set.
+attrs = { x = 1280; y = 1024; };
+</programlisting>
+
+  </para></listitem>
+
+  <listitem><para>Breaking in the middle of a function argument can
+  give hard-to-read code, like
+
+<programlisting>
+someFunction { x = 1280;
+  y = 1024; } otherArg
+  yetAnotherArg
+</programlisting>
+
+  (especially if the argument is very large, spanning multiple
+  lines).</para>
+
+  <para>Better:
+
+<programlisting>
+someFunction
+  { x = 1280; y = 1024; }
+  otherArg
+  yetAnotherArg
+</programlisting>
+
+  or
+
+<programlisting>
+let res = { x = 1280; y = 1024; };
+in someFunction res otherArg yetAnotherArg
+</programlisting>
+
+  </para></listitem>
+
+  <listitem><para>The bodies of functions, asserts, and withs are not
+  indented to prevent a lot of superfluous indentation levels, i.e.
+
+<programlisting>
+{ arg1, arg2 }:
+assert system == "i686-linux";
+stdenv.mkDerivation { ...
+</programlisting>
+
+  not
+
+<programlisting>
+{ arg1, arg2 }:
+  assert system == "i686-linux";
+    stdenv.mkDerivation { ...
+</programlisting>
+
+  </para></listitem>
+
+  <listitem><para>Function formal arguments are written as:
+
+<programlisting>
+{ arg1, arg2, arg3 }:
+</programlisting>
+
+  but if they don't fit on one line they're written as:
+
+<programlisting>
+{ arg1, arg2, arg3
+, arg4, ...
+, # Some comment...
+  argN
+}:
+</programlisting>
+
+  </para></listitem>
+
+</itemizedlist>
+
+</section>
+
+
+<section><title>File naming and organisation</title>
+
+<para>Names of files and directories should be in lowercase, with
+dashes between words — not in camel case.  For instance, it should be
+<filename>all-packages.nix</filename>, not
+<filename>allPackages.nix</filename> or
+<filename>AllPackages.nix</filename>.</para>
+
+</section>
+
+
+</chapter>

doc/manual.xml

@@ -33,6 +33,7 @@
   <xi:include href="meta.xml" />
   <xi:include href="language-support.xml" />
   <xi:include href="package-notes.xml" />
+  <xi:include href="coding-conventions.xml" />
   
         
 </book>

maintainers/docs/bugs.txt

@@ -1,49 +0,0 @@
-*** All these bugs should be moved to JIRA (if they still exist) ***
-
-
-* If NIX_DEBUG is turned on (set to "1"), autoconf configure scripts
-  may fail to find the correct preprocessor:
-
-    checking how to run the C preprocessor... /lib/cpp
-
-
-* When building gcc using a Nix gcc, generated libraries link against
-  the libraries of the latter:
-
-    $ ldd /nix/store/3b1d3995c4edbf026be5c73f66f69245-gcc-3.3.3/lib/libstdc++.so
-    ...
-    libgcc_s.so.1 => /nix/store/1f19e61d1b7051f1131f78b41b2a0e7e-gcc-3.3.2/lib/libgcc_s.so.1 (0x400de000)
-    (wrong! should be .../3b1d.../lib/libgcc_s...)
-    ...
-
-
-* In libXt:
-
-/bin/sh ./libtool --mode=compile gcc -DHAVE_CONFIG_H -I. -I. -I.     -DXTHREADS -DXUSE_MTSAFE_API -I/nix/store/aadf0bd4a908da11d14f6538503b8408-libX11-6.2.1/include -I/nix/store/ba366e3b944ead64ec9b0490bb615874-xproto-6.6.1/include   -I./include/X11 -g -O2 -c -o ActionHook.lo `test -f 'ActionHook.c' || echo './'`ActionHook.c
-mkdir .libs
- gcc -DHAVE_CONFIG_H -I. -I. -I. -DXTHREADS -DXUSE_MTSAFE_API -I/nix/store/aadf0bd4a908da11d14f6538503b8408-libX11-6.2.1/include -I/nix/store/ba366e3b944ead64ec9b0490bb615874-xproto-6.6.1/include -I./include/X11 -g -O2 -c ActionHook.c  -fPIC -DPIC -o .libs/ActionHook.o
-In file included from IntrinsicI.h:55,
-                 from ActionHook.c:69:
-include/X11/IntrinsicP.h:54:27: X11/Intrinsic.h: No such file or directory
-
-
-* Then:
-
- gcc -DHAVE_CONFIG_H -I. -I. -I. -DXTHREADS -DXUSE_MTSAFE_API -I/nix/store/aadf0bd4a908da11d14f6538503b8408-libX11-6.2.1/include -I/nix/store/ba366e3b944ead64ec9b0490bb615874-xproto-6.6.1/include -I./include -I./include/X11 -g -O2 -c ActionHook.c  -fPIC -DPIC -o .libs/ActionHook.o
-In file included from IntrinsicI.h:55,
-                 from ActionHook.c:69:
-include/X11/IntrinsicP.h:202:25: X11/ObjectP.h: No such file or directory
-
-(moved to include/X11; should edit include/Makefile.am)
-
-
-* In gtksourceview-sharp: does the prefix patch cause problems (e.g.,
-  makefile.am says "mimeinfodir should be the same as the gnome
-  prefix")?
-
-
-* fgrep/egrep: these fail if grep is not in the $PATH.
-
-
-* teTeX: some programs (such as epstopdf) depend on /usr/bin/env, and
-  expect perl to be in the environment.

maintainers/docs/coding-conventions.txt

@@ -1,101 +0,0 @@
-Some conventions:
-
-* Directories / file names: lowercase, and use dashes between words,
-  no camel case.  I.e., all-packages.nix, not all allPackages.nix or
-  AllPackages.nix.
-
-* Don't use TABs.  Everybody has different TAB settings so it's asking
-  for trouble.
-
-* Use 2 spaces of indentation per indentation level in Nix
-  expressions, 4 spaces in shell scripts.  (Maybe 2 is too low, but
-  for consistency's sake it should be the same.  Certainly indentation
-  should be consistent within a single file.)
-
-* Use lowerCamelCase for variable names, not UpperCamelCase.
-
-* Function calls with attribute set arguments are written as
-
-    foo {
-      arg = ...;
-    }
-
-  not
-
-    foo
-    {
-      arg = ...;
-    }
-
-  Also fine is
-
-    foo { arg = ...; }
-
-  if it's a short call.
-
-* In attribute sets or lists that span multiple lines, the attribute
-  names or list elements should be aligned:
-
-    # A long list.
-    list = [
-      elem1
-      elem2
-      elem3
-    ];
-
-    # A long attribute set.
-    attrs = {
-      attr1 = short_expr;
-      attr2 =
-        if true then big_expr else big_expr;
-    };
-    
-* Short lists or attribute sets can be written on one line:
-    
-    # A short list.
-    list = [ elem1 elem2 elem3 ];
-
-    # A short set.
-    attrs = { x = 1280; y = 1024; };
-
-* Breaking in the middle of a function argument can give hard-to-read
-  code, like
-
-    someFunction { x = 1280;
-      y = 1024; } otherArg
-      yetAnotherArg
-
-  (especially if the argument is very large, spanning multiple lines).
-
-  Better:
-
-    someFunction
-      { x = 1280; y = 1024; }
-      otherArg
-      yetAnotherArg
-
-  or
-    
-    let res = { x = 1280; y = 1024; };
-    in someFunction res otherArg yetAnotherArg
-
-* The bodies of functions, asserts, and withs are not indented, so
-
-    assert system == "i686-linux";
-    stdenv.mkDerivation { ...
-
-  not
-
-    assert system == "i686-linux";
-      stdenv.mkDerivation { ...
-
-* Function formal arguments are written as:
-
-    {arg1, arg2, arg3}:
-
-  but if they don't fit on one line they're written as:
-
-    { arg1, arg2, arg3
-    , arg4, ...
-    , argN
-    }:

maintainers/docs/create-new-static-env

@@ -1,31 +0,0 @@
-Creating a new static stdenv
-----------------------------
-
-When Nix is ported to a new (Linux) platform and you want to have a completely
-pure setup for the stdenv (for example for NixOS) it is necessary to rebuild
-the static tools.
-
-The challenge is that there is no Nix environment yet, for bootstrapping.
-The first task is to create all the tools that are necessary. For most tools
-there are ready made Nix expressions.
-
-
-  GCC
-
-There is an expression gcc-static-3.4. Depending on whether or not you already
-have an environment built with Nix (x86-linux: yes, rest: not yet) you should
-set the noSysDirs parameter in all-packages.nix. If there is an environment,
-leave it, but if the system is still impure (like most systems), set noSysDirs
-to false.
-
-  bash
-
-There is an expression for bash-static. Simply build it.
-
-  bzip2
-
-There is an expression for bzip2-static. Simply build it.
-
-  findutils
-
-There is an expression for findutils-static. Simply build it.

maintainers/docs/static-initial-env

@@ -1,35 +0,0 @@
-Upgrading the standard initial environment
-
-For Nix on i686-linux we make use of an environment of statically linked
-tools (see $nixpkgs/stdenv/linux). The first version of these tools were
-compiled outside of Nix, in an impure environment. They are used as some
-magical ingredient to make everything work. To keep these tools more in
-synchronization with the rest of nixpkgs and to make porting of nixpkgs
-to other platforms easier the static versions are now also built with Nix
-and nixpkgs.
-
-The tools can be found in nixpkgs in:
-
-- shells/bash-static
-- tools/networking/curl-diet
-- tools/archivers/gnutar-diet
-- tools/compression/gzip-diet
-- tools/compression/bzip2-static
-- tools/text/gnused-diet
-- tools/text/diffutils-diet
-- tools/text/gnupatch-diet
-- tools/misc/findutils-static
-
-and
-- development/compilers/gcc-static-3.4
-
-Most packages are compiled with dietlibc, an alternate C library, apart
-from bash and findutils, which are statically linked to glibc. The reason
-we chose dietlibc has various reasons. First of all, curl cannot be built
-statically with glibc. If we do, we get a static binary, but it cannot resolve
-hostnames to IP addresses. glibc dynamically loads functionality at runtime
-to do resolving. When linking with dietlibc this doesn't happen.
-
-The static tools are not used as part of the input hashing (see Eelco's
-PhD thesis, paragraph 5.4.1), so changing them does not change anything and
-will not force a massive rebuild.

maintainers/docs/todo.txt

@@ -1,12 +0,0 @@
-* Patch development/tools/misc/libtool not to search standard
-  directories for libraries (like setup.sh does now). [do we want
-  this?]
-
-* Inform freedesktop people that Xaw requires Xpm.
-
-* After building gcc, filter out references to /tmp/nix... in
-  .../lib/libsupc++.la and .../lib/libstdc++.la
-
-* Add gettext to glib propagatedBuildInputs?  Glib's `gi18n.h' doesn't
-  seem to like Glibc `libintl.h'; needs the gettext one instead.
-  [Move from libbonoboui]