diff options
| -rw-r--r-- | doc/coding-conventions.xml | 175 | ||||
| -rw-r--r-- | doc/manual.xml | 1 | ||||
| -rw-r--r-- | maintainers/docs/bugs.txt | 49 | ||||
| -rw-r--r-- | maintainers/docs/coding-conventions.txt | 101 | ||||
| -rw-r--r-- | maintainers/docs/create-new-static-env | 31 | ||||
| -rw-r--r-- | maintainers/docs/static-initial-env | 35 | ||||
| -rw-r--r-- | maintainers/docs/todo.txt | 12 |
7 files changed, 176 insertions, 228 deletions
diff --git a/doc/coding-conventions.xml b/doc/coding-conventions.xml new file mode 100644 index 0000000000000..3e4afdc1d4f5f --- /dev/null +++ b/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> \ No newline at end of file diff --git a/doc/manual.xml b/doc/manual.xml index 036cc437d14b5..881528e7cd9a7 100644 --- a/doc/manual.xml +++ b/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> diff --git a/maintainers/docs/bugs.txt b/maintainers/docs/bugs.txt deleted file mode 100644 index 5a15437c31121..0000000000000 --- a/maintainers/docs/bugs.txt +++ /dev/null @@ -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. diff --git a/maintainers/docs/coding-conventions.txt b/maintainers/docs/coding-conventions.txt deleted file mode 100644 index 2cff1c33d7ee5..0000000000000 --- a/maintainers/docs/coding-conventions.txt +++ /dev/null @@ -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 - }: diff --git a/maintainers/docs/create-new-static-env b/maintainers/docs/create-new-static-env deleted file mode 100644 index 32887e3c20b18..0000000000000 --- a/maintainers/docs/create-new-static-env +++ /dev/null @@ -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. diff --git a/maintainers/docs/static-initial-env b/maintainers/docs/static-initial-env deleted file mode 100644 index 8db23d6f852dc..0000000000000 --- a/maintainers/docs/static-initial-env +++ /dev/null @@ -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. diff --git a/maintainers/docs/todo.txt b/maintainers/docs/todo.txt deleted file mode 100644 index adf1c0dff589f..0000000000000 --- a/maintainers/docs/todo.txt +++ /dev/null @@ -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] |