JakeHillion/nixpkgs
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

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

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

svn path=/nixpkgs/trunk/; revision=17419
This commit is contained in:
Eelco Dolstra 2009-09-25 14:27:26 +00:00
parent 24da0cbad8
commit bfb4a0ccc8
7 changed files with 176 additions and 228 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

175
doc/coding-conventions.xml Normal file
View File

@ -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>

1
doc/manual.xml
View File

@ -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>

49
maintainers/docs/bugs.txt
View File

@ -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.

101
maintainers/docs/coding-conventions.txt
View File

@ -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
}:

31
maintainers/docs/create-new-static-env
View File

@ -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.

35
maintainers/docs/static-initial-env
View File

@ -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.

12
maintainers/docs/todo.txt
View File

@ -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]