mirror of
https://github.com/NixOS/nixpkgs.git
synced 2024-10-31 06:31:20 +00:00
* 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
This commit is contained in:
parent
24da0cbad8
commit
bfb4a0ccc8
175
doc/coding-conventions.xml
Normal file
175
doc/coding-conventions.xml
Normal 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>
|
@ -33,6 +33,7 @@
|
|||||||
<xi:include href="meta.xml" />
|
<xi:include href="meta.xml" />
|
||||||
<xi:include href="language-support.xml" />
|
<xi:include href="language-support.xml" />
|
||||||
<xi:include href="package-notes.xml" />
|
<xi:include href="package-notes.xml" />
|
||||||
|
<xi:include href="coding-conventions.xml" />
|
||||||
|
|
||||||
|
|
||||||
</book>
|
</book>
|
||||||
|
@ -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.
|
|
@ -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
|
|
||||||
}:
|
|
@ -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.
|
|
@ -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.
|
|
@ -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]
|
|
Loading…
Reference in New Issue
Block a user