commit
f18ddabee7
@ -0,0 +1,16 @@ |
||||
**/deps.nix linguist-generated |
||||
**/node-packages.nix linguist-generated |
||||
|
||||
pkgs/applications/editors/emacs-modes/*-generated.nix linguist-generated |
||||
pkgs/development/r-modules/*-packages.nix linguist-generated |
||||
pkgs/development/haskell-modules/hackage-packages.nix linguist-generated |
||||
pkgs/development/beam-modules/hex-packages.nix linguist-generated |
||||
|
||||
doc/** linguist-documentation |
||||
doc/default.nix linguist-documentation=false |
||||
|
||||
nixos/doc/** linguist-documentation |
||||
nixos/doc/default.nix linguist-documentation=false |
||||
|
||||
nixos/modules/module-list.nix merge=union |
||||
# pkgs/top-level/all-packages.nix merge=union |
@ -0,0 +1,6 @@ |
||||
*.chapter.xml |
||||
*.section.xml |
||||
.version |
||||
out |
||||
manual-full.xml |
||||
highlightjs |
@ -0,0 +1,95 @@ |
||||
MD_TARGETS=$(addsuffix .xml, $(basename $(wildcard ./*.md ./**/*.md)))
|
||||
|
||||
.PHONY: all |
||||
all: validate format out/html/index.html out/epub/manual.epub |
||||
|
||||
.PHONY: debug |
||||
debug: |
||||
nix-shell --run "xmloscopy --docbook5 ./manual.xml ./manual-full.xml"
|
||||
|
||||
.PHONY: format |
||||
format: |
||||
find . -iname '*.xml' -type f -print0 | xargs -0 -I{} -n1 \
|
||||
xmlformat --config-file "$$XMLFORMAT_CONFIG" -i {}
|
||||
|
||||
.PHONY: clean |
||||
clean: |
||||
rm -f ${MD_TARGETS} .version manual-full.xml
|
||||
rm -rf ./out/ ./highlightjs
|
||||
|
||||
.PHONY: validate |
||||
validate: manual-full.xml |
||||
jing "$$RNG" manual-full.xml
|
||||
|
||||
out/html/index.html: manual-full.xml style.css highlightjs |
||||
mkdir -p out/html
|
||||
xsltproc ${xsltFlags} \
|
||||
--nonet --xinclude \
|
||||
--output $@ \
|
||||
"$$XSL/docbook/xhtml/docbook.xsl" \
|
||||
./manual-full.xml
|
||||
|
||||
mkdir -p out/html/highlightjs/
|
||||
cp -r highlightjs out/html/
|
||||
|
||||
cp ./overrides.css out/html/
|
||||
cp ./style.css out/html/style.css
|
||||
|
||||
mkdir -p out/html/images/callouts
|
||||
cp "$$XSL/docbook/images/callouts/"*.svg out/html/images/callouts/
|
||||
chmod u+w -R out/html/
|
||||
|
||||
out/epub/manual.epub: manual-full.xml |
||||
mkdir -p out/epub/scratch
|
||||
xsltproc ${xsltFlags} --nonet \
|
||||
--output out/epub/scratch/ \
|
||||
"$$XSL/docbook/epub/docbook.xsl" \
|
||||
./manual-full.xml
|
||||
|
||||
cp ./overrides.css out/epub/scratch/OEBPS
|
||||
cp ./style.css out/epub/scratch/OEBPS
|
||||
mkdir -p out/epub/scratch/OEBPS/images/callouts/
|
||||
cp "$$XSL/docbook/images/callouts/"*.svg out/epub/scratch/OEBPS/images/callouts/
|
||||
echo "application/epub+zip" > mimetype
|
||||
zip -0Xq "out/epub/manual.epub" mimetype
|
||||
rm mimetype
|
||||
cd "out/epub/scratch/" && zip -Xr9D "../manual.epub" *
|
||||
rm -rf "out/epub/scratch/"
|
||||
|
||||
highlightjs: |
||||
mkdir -p highlightjs
|
||||
cp -r "$$HIGHLIGHTJS/highlight.pack.js" highlightjs/
|
||||
cp -r "$$HIGHLIGHTJS/LICENSE" highlightjs/
|
||||
cp -r "$$HIGHLIGHTJS/mono-blue.css" highlightjs/
|
||||
cp -r "$$HIGHLIGHTJS/loader.js" highlightjs/
|
||||
|
||||
|
||||
manual-full.xml: ${MD_TARGETS} .version *.xml |
||||
xmllint --nonet --xinclude --noxincludenode manual.xml --output manual-full.xml
|
||||
|
||||
.version: |
||||
nix-instantiate --eval \
|
||||
-E '(import ../lib).version' > .version
|
||||
|
||||
%.section.xml: %.section.md |
||||
pandoc $^ -w docbook+smart \
|
||||
-f markdown+smart \
|
||||
| sed -e 's|<ulink url=|<link xlink:href=|' \
|
||||
-e 's|</ulink>|</link>|' \
|
||||
-e 's|<sect. id=|<section xml:id=|' \
|
||||
-e 's|</sect[0-9]>|</section>|' \
|
||||
-e '1s| id=| xml:id=|' \
|
||||
-e '1s|\(<[^ ]* \)|\1xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" |' \
|
||||
| cat > $@
|
||||
|
||||
%.chapter.xml: %.chapter.md |
||||
pandoc $^ -w docbook+smart \
|
||||
--top-level-division=chapter \
|
||||
-f markdown+smart \
|
||||
| sed -e 's|<ulink url=|<link xlink:href=|' \
|
||||
-e 's|</ulink>|</link>|' \
|
||||
-e 's|<sect. id=|<section xml:id=|' \
|
||||
-e 's|</sect[0-9]>|</section>|' \
|
||||
-e '1s| id=| xml:id=|' \
|
||||
-e '1s|\(<[^ ]* \)|\1|' \
|
||||
| cat > $@
|
File diff suppressed because it is too large
Load Diff
@ -1,20 +1,35 @@ |
||||
<chapter xmlns="http://docbook.org/ns/docbook" |
||||
xmlns:xlink="http://www.w3.org/1999/xlink" |
||||
xml:id="chap-contributing"> |
||||
|
||||
<title>Contributing to this documentation</title> |
||||
|
||||
<para>The DocBook sources of the Nixpkgs manual are in the <filename |
||||
<title>Contributing to this documentation</title> |
||||
<para> |
||||
The DocBook sources of the Nixpkgs manual are in the |
||||
<filename |
||||
xlink:href="https://github.com/NixOS/nixpkgs/tree/master/doc">doc</filename> |
||||
subdirectory of the Nixpkgs repository. If you make modifications to |
||||
the manual, it's important to build it before committing. You can do that as follows: |
||||
|
||||
subdirectory of the Nixpkgs repository. |
||||
</para> |
||||
<para> |
||||
You can quickly check your edits with <command>make</command>: |
||||
</para> |
||||
<screen> |
||||
$ cd /path/to/nixpkgs |
||||
$ nix-build doc |
||||
$ cd /path/to/nixpkgs/doc |
||||
$ nix-shell |
||||
[nix-shell]$ make |
||||
</screen> |
||||
|
||||
If the build succeeds, the manual will be in |
||||
<filename>./result/share/doc/nixpkgs/manual.html</filename>.</para> |
||||
|
||||
<para> |
||||
If you experience problems, run <command>make debug</command> to help |
||||
understand the docbook errors. |
||||
</para> |
||||
<para> |
||||
After making modifications to the manual, it's important to build it before |
||||
committing. You can do that as follows: |
||||
<screen> |
||||
$ cd /path/to/nixpkgs/doc |
||||
$ nix-shell |
||||
[nix-shell]$ make clean |
||||
[nix-shell]$ nix-build . |
||||
</screen> |
||||
If the build succeeds, the manual will be in |
||||
<filename>./result/share/doc/nixpkgs/manual.html</filename>. |
||||
</para> |
||||
</chapter> |
||||
|
@ -1,308 +1,469 @@ |
||||
<chapter xmlns="http://docbook.org/ns/docbook" |
||||
xmlns:xlink="http://www.w3.org/1999/xlink" |
||||
xml:id="chap-cross"> |
||||
|
||||
<title>Cross-compilation</title> |
||||
|
||||
<section xml:id="sec-cross-intro"> |
||||
<title>Cross-compilation</title> |
||||
<section xml:id="sec-cross-intro"> |
||||
<title>Introduction</title> |
||||
|
||||
<para> |
||||
"Cross-compilation" means compiling a program on one machine for another type of machine. |
||||
For example, a typical use of cross compilation is to compile programs for embedded devices. |
||||
These devices often don't have the computing power and memory to compile their own programs. |
||||
One might think that cross-compilation is a fairly niche concern, but there are advantages to being rigorous about distinguishing build-time vs run-time environments even when one is developing and deploying on the same machine. |
||||
Nixpkgs is increasingly adopting the opinion that packages should be written with cross-compilation in mind, and nixpkgs should evaluate in a similar way (by minimizing cross-compilation-specific special cases) whether or not one is cross-compiling. |
||||
"Cross-compilation" means compiling a program on one machine for another |
||||
type of machine. For example, a typical use of cross compilation is to |
||||
compile programs for embedded devices. These devices often don't have the |
||||
computing power and memory to compile their own programs. One might think |
||||
that cross-compilation is a fairly niche concern, but there are advantages |
||||
to being rigorous about distinguishing build-time vs run-time environments |
||||
even when one is developing and deploying on the same machine. Nixpkgs is |
||||
increasingly adopting the opinion that packages should be written with |
||||
cross-compilation in mind, and nixpkgs should evaluate in a similar way (by |
||||
minimizing cross-compilation-specific special cases) whether or not one is |
||||
cross-compiling. |
||||
</para> |
||||
|
||||
<para> |
||||
This chapter will be organized in three parts. |
||||
First, it will describe the basics of how to package software in a way that supports cross-compilation. |
||||
Second, it will describe how to use Nixpkgs when cross-compiling. |
||||
Third, it will describe the internal infrastructure supporting cross-compilation. |
||||
This chapter will be organized in three parts. First, it will describe the |
||||
basics of how to package software in a way that supports cross-compilation. |
||||
Second, it will describe how to use Nixpkgs when cross-compiling. Third, it |
||||
will describe the internal infrastructure supporting cross-compilation. |
||||
</para> |
||||
</section> |
||||
|
||||
</section> |
||||
<!--============================================================--> |
||||
|
||||
<section xml:id="sec-cross-packaging"> |
||||
<section xml:id="sec-cross-packaging"> |
||||
<title>Packaging in a cross-friendly manner</title> |
||||
|
||||
<section> |
||||
<title>Platform parameters</title> |
||||
<para> |
||||
Nixpkgs follows the <link xlink:href="https://gcc.gnu.org/onlinedocs/gccint/Configure-Terms.html">common historical convention of GNU autoconf</link> of distinguishing between 3 types of platform: <wordasword>build</wordasword>, <wordasword>host</wordasword>, and <wordasword>target</wordasword>. |
||||
<title>Platform parameters</title> |
||||
|
||||
In summary, <wordasword>build</wordasword> is the platform on which a package is being built, <wordasword>host</wordasword> is the platform on which it is to run. The third attribute, <wordasword>target</wordasword>, is relevant only for certain specific compilers and build tools. |
||||
</para> |
||||
<para> |
||||
Nixpkgs follows the |
||||
<link xlink:href="https://gcc.gnu.org/onlinedocs/gccint/Configure-Terms.html">common |
||||
historical convention of GNU autoconf</link> of distinguishing between 3 |
||||
types of platform: <wordasword>build</wordasword>, |
||||
<wordasword>host</wordasword>, and <wordasword>target</wordasword>. In |
||||
summary, <wordasword>build</wordasword> is the platform on which a package |
||||
is being built, <wordasword>host</wordasword> is the platform on which it |
||||
is to run. The third attribute, <wordasword>target</wordasword>, is |
||||
relevant only for certain specific compilers and build tools. |
||||
</para> |
||||
|
||||
<para> |
||||
In Nixpkgs, these three platforms are defined as attribute sets under the names <literal>buildPlatform</literal>, <literal>hostPlatform</literal>, and <literal>targetPlatform</literal>. |
||||
All three are always defined as attributes in the standard environment, and at the top level. That means one can get at them just like a dependency in a function that is imported with <literal>callPackage</literal>: |
||||
<programlisting>{ stdenv, buildPlatform, hostPlatform, fooDep, barDep, .. }: ...buildPlatform...</programlisting>, or just off <varname>stdenv</varname>: |
||||
<programlisting>{ stdenv, fooDep, barDep, .. }: ...stdenv.buildPlatform...</programlisting>. |
||||
</para> |
||||
<variablelist> |
||||
<varlistentry> |
||||
<term><varname>buildPlatform</varname></term> |
||||
<listitem><para> |
||||
The "build platform" is the platform on which a package is built. |
||||
Once someone has a built package, or pre-built binary package, the build platform should not matter and be safe to ignore. |
||||
</para></listitem> |
||||
</varlistentry> |
||||
<varlistentry> |
||||
<term><varname>hostPlatform</varname></term> |
||||
<listitem><para> |
||||
The "host platform" is the platform on which a package will be run. |
||||
This is the simplest platform to understand, but also the one with the worst name. |
||||
</para></listitem> |
||||
</varlistentry> |
||||
<varlistentry> |
||||
<term><varname>targetPlatform</varname></term> |
||||
<listitem> |
||||
<para> |
||||
The "target platform" attribute is, unlike the other two attributes, not actually fundamental to the process of building software. |
||||
Instead, it is only relevant for compatibility with building certain specific compilers and build tools. |
||||
It can be safely ignored for all other packages. |
||||
</para> |
||||
<para> |
||||
The build process of certain compilers is written in such a way that the compiler resulting from a single build can itself only produce binaries for a single platform. |
||||
The task specifying this single "target platform" is thus pushed to build time of the compiler. |
||||
The root cause of this mistake is often that the compiler (which will be run on the host) and the the standard library/runtime (which will be run on the target) are built by a single build process. |
||||
</para> |
||||
<para> |
||||
There is no fundamental need to think about a single target ahead of time like this. |
||||
If the tool supports modular or pluggable backends, both the need to specify the target at build time and the constraint of having only a single target disappear. |
||||
An example of such a tool is LLVM. |
||||
</para> |
||||
<para> |
||||
Although the existance of a "target platfom" is arguably a historical mistake, it is a common one: examples of tools that suffer from it are GCC, Binutils, GHC and Autoconf. |
||||
Nixpkgs tries to avoid sharing in the mistake where possible. |
||||
Still, because the concept of a target platform is so ingrained, it is best to support it as is. |
||||
</para> |
||||
</listitem> |
||||
</varlistentry> |
||||
</variablelist> |
||||
<para> |
||||
The exact schema these fields follow is a bit ill-defined due to a long and convoluted evolution, but this is slowly being cleaned up. |
||||
You can see examples of ones used in practice in <literal>lib.systems.examples</literal>; note how they are not all very consistent. |
||||
For now, here are few fields can count on them containing: |
||||
</para> |
||||
<variablelist> |
||||
<varlistentry> |
||||
<term><varname>system</varname></term> |
||||
<listitem> |
||||
<para> |
||||
This is a two-component shorthand for the platform. |
||||
Examples of this would be "x86_64-darwin" and "i686-linux"; see <literal>lib.systems.doubles</literal> for more. |
||||
This format isn't very standard, but has built-in support in Nix, such as the <varname>builtins.currentSystem</varname> impure string. |
||||
</para> |
||||
</listitem> |
||||
</varlistentry> |
||||
<varlistentry> |
||||
<term><varname>config</varname></term> |
||||
<listitem> |
||||
<para> |
||||
This is a 3- or 4- component shorthand for the platform. |
||||
Examples of this would be "x86_64-unknown-linux-gnu" and "aarch64-apple-darwin14". |
||||
This is a standard format called the "LLVM target triple", as they are pioneered by LLVM and traditionally just used for the <varname>targetPlatform</varname>. |
||||
This format is strictly more informative than the "Nix host double", as the previous format could analogously be termed. |
||||
This needs a better name than <varname>config</varname>! |
||||
</para> |
||||
</listitem> |
||||
</varlistentry> |
||||
<varlistentry> |
||||
<term><varname>parsed</varname></term> |
||||
<listitem> |
||||
<para> |
||||
This is a nix representation of a parsed LLVM target triple with white-listed components. |
||||
This can be specified directly, or actually parsed from the <varname>config</varname>. |
||||
[Technically, only one need be specified and the others can be inferred, though the precision of inference may not be very good.] |
||||
See <literal>lib.systems.parse</literal> for the exact representation. |
||||
</para> |
||||
</listitem> |
||||
</varlistentry> |
||||
<varlistentry> |
||||
<term><varname>libc</varname></term> |
||||
<listitem> |
||||
<para> |
||||
This is a string identifying the standard C library used. |
||||
Valid identifiers include "glibc" for GNU libc, "libSystem" for Darwin's Libsystem, and "uclibc" for µClibc. |
||||
It should probably be refactored to use the module system, like <varname>parse</varname>. |
||||
</para> |
||||
</listitem> |
||||
</varlistentry> |
||||
<varlistentry> |
||||
<term><varname>is*</varname></term> |
||||
<listitem> |
||||
<para> |
||||
These predicates are defined in <literal>lib.systems.inspect</literal>, and slapped on every platform. |
||||
They are superior to the ones in <varname>stdenv</varname> as they force the user to be explicit about which platform they are inspecting. |
||||
Please use these instead of those. |
||||
</para> |
||||
</listitem> |
||||
</varlistentry> |
||||
<varlistentry> |
||||
<term><varname>platform</varname></term> |
||||
<listitem> |
||||
<para> |
||||
This is, quite frankly, a dumping ground of ad-hoc settings (it's an attribute set). |
||||
See <literal>lib.systems.platforms</literal> for examples—there's hopefully one in there that will work verbatim for each platform that is working. |
||||
Please help us triage these flags and give them better homes! |
||||
</para> |
||||
</listitem> |
||||
</varlistentry> |
||||
</variablelist> |
||||
<para> |
||||
In Nixpkgs, these three platforms are defined as attribute sets under the |
||||
names <literal>buildPlatform</literal>, <literal>hostPlatform</literal>, |
||||
and <literal>targetPlatform</literal>. All three are always defined as |
||||
attributes in the standard environment, and at the top level. That means |
||||
one can get at them just like a dependency in a function that is imported |
||||
with <literal>callPackage</literal>: |
||||
<programlisting>{ stdenv, buildPlatform, hostPlatform, fooDep, barDep, .. }: ...buildPlatform...</programlisting> |
||||
, or just off <varname>stdenv</varname>: |
||||
<programlisting>{ stdenv, fooDep, barDep, .. }: ...stdenv.buildPlatform...</programlisting> |
||||
. |
||||
</para> |
||||
|
||||
<variablelist> |
||||
<varlistentry> |
||||
<term><varname>buildPlatform</varname> |
||||
</term> |
||||
<listitem> |
||||
<para> |
||||
The "build platform" is the platform on which a package is built. Once |
||||
someone has a built package, or pre-built binary package, the build |
||||
platform should not matter and be safe to ignore. |
||||
</para> |
||||
</listitem> |
||||
</varlistentry> |
||||
<varlistentry> |
||||
<term><varname>hostPlatform</varname> |
||||
</term> |
||||
<listitem> |
||||
<para> |
||||
The "host platform" is the platform on which a package will be run. This |
||||
is the simplest platform to understand, but also the one with the worst |
||||
name. |
||||
</para> |
||||
</listitem> |
||||
</varlistentry> |
||||
<varlistentry> |
||||
<term><varname>targetPlatform</varname> |
||||
</term> |
||||
<listitem> |
||||
<para> |
||||
The "target platform" attribute is, unlike the other two attributes, not |
||||
actually fundamental to the process of building software. Instead, it is |
||||
only relevant for compatibility with building certain specific compilers |
||||
and build tools. It can be safely ignored for all other packages. |
||||
</para> |
||||
<para> |
||||
The build process of certain compilers is written in such a way that the |
||||
compiler resulting from a single build can itself only produce binaries |
||||
for a single platform. The task specifying this single "target platform" |
||||
is thus pushed to build time of the compiler. The root cause of this |
||||
mistake is often that the compiler (which will be run on the host) and |
||||
the the standard library/runtime (which will be run on the target) are |
||||
built by a single build process. |
||||
</para> |
||||
<para> |
||||
There is no fundamental need to think about a single target ahead of |
||||
time like this. If the tool supports modular or pluggable backends, both |
||||
the need to specify the target at build time and the constraint of |
||||
having only a single target disappear. An example of such a tool is |
||||
LLVM. |
||||
</para> |
||||
<para> |
||||
Although the existence of a "target platfom" is arguably a historical |
||||
mistake, it is a common one: examples of tools that suffer from it are |
||||
GCC, Binutils, GHC and Autoconf. Nixpkgs tries to avoid sharing in the |
||||
mistake where possible. Still, because the concept of a target platform |
||||
is so ingrained, it is best to support it as is. |
||||
</para> |
||||
</listitem> |
||||
</varlistentry> |
||||
</variablelist> |
||||
|
||||
<para> |
||||
The exact schema these fields follow is a bit ill-defined due to a long and |
||||
convoluted evolution, but this is slowly being cleaned up. You can see |
||||
examples of ones used in practice in |
||||
<literal>lib.systems.examples</literal>; note how they are not all very |
||||
consistent. For now, here are few fields can count on them containing: |
||||
</para> |
||||
|
||||
<variablelist> |
||||
<varlistentry> |
||||
<term><varname>system</varname> |
||||
</term> |
||||
<listitem> |
||||
<para> |
||||
This is a two-component shorthand for the platform. Examples of this |
||||
would be "x86_64-darwin" and "i686-linux"; see |
||||
<literal>lib.systems.doubles</literal> for more. This format isn't very |
||||
standard, but has built-in support in Nix, such as the |
||||
<varname>builtins.currentSystem</varname> impure string. |
||||
</para> |
||||
</listitem> |
||||
</varlistentry> |
||||
<varlistentry> |
||||
<term><varname>config</varname> |
||||
</term> |
||||
<listitem> |
||||
<para> |
||||
This is a 3- or 4- component shorthand for the platform. Examples of |
||||
this would be "x86_64-unknown-linux-gnu" and "aarch64-apple-darwin14". |
||||
This is a standard format called the "LLVM target triple", as they are |
||||
pioneered by LLVM and traditionally just used for the |
||||
<varname>targetPlatform</varname>. This format is strictly more |
||||
informative than the "Nix host double", as the previous format could |
||||
analogously be termed. This needs a better name than |
||||
<varname>config</varname>! |
||||
</para> |
||||
</listitem> |
||||
</varlistentry> |
||||
<varlistentry> |
||||
<term><varname>parsed</varname> |
||||
</term> |
||||
<listitem> |
||||
<para> |
||||
This is a nix representation of a parsed LLVM target triple with |
||||
white-listed components. This can be specified directly, or actually |
||||
parsed from the <varname>config</varname>. [Technically, only one need |
||||
be specified and the others can be inferred, though the precision of |
||||
inference may not be very good.] See |
||||
<literal>lib.systems.parse</literal> for the exact representation. |
||||
</para> |
||||
</listitem> |
||||
</varlistentry> |
||||
<varlistentry> |
||||
<term><varname>libc</varname> |
||||
</term> |
||||
<listitem> |
||||
<para> |
||||
This is a string identifying the standard C library used. Valid |
||||
identifiers include "glibc" for GNU libc, "libSystem" for Darwin's |
||||
Libsystem, and "uclibc" for µClibc. It should probably be refactored to |
||||
use the module system, like <varname>parse</varname>. |
||||
</para> |
||||
</listitem> |
||||
</varlistentry> |
||||
<varlistentry> |
||||
<term><varname>is*</varname> |
||||
</term> |
||||
<listitem> |
||||
<para> |
||||
These predicates are defined in <literal>lib.systems.inspect</literal>, |
||||
and slapped on every platform. They are superior to the ones in |
||||
<varname>stdenv</varname> as they force the user to be explicit about |
||||
which platform they are inspecting. Please use these instead of those. |
||||
</para> |
||||
</listitem> |
||||
</varlistentry> |
||||
<varlistentry> |
||||
<term><varname>platform</varname> |
||||
</term> |
||||
<listitem> |
||||
<para> |
||||
This is, quite frankly, a dumping ground of ad-hoc settings (it's an |
||||
attribute set). See <literal>lib.systems.platforms</literal> for |
||||
examples—there's hopefully one in there that will work verbatim for |
||||
each platform that is working. Please help us triage these flags and |
||||
give them better homes! |
||||
</para> |
||||
</listitem> |
||||
</varlistentry> |
||||
</variablelist> |
||||
</section> |
||||
|
||||
<section> |
||||
<title>Specifying Dependencies</title> |
||||
<para> |
||||
In this section we explore the relationship between both runtime and buildtime dependencies and the 3 Autoconf platforms. |
||||
</para> |
||||
<para> |
||||
A runtime dependency between 2 packages implies that between them both the host and target platforms match. |
||||
This is directly implied by the meaning of "host platform" and "runtime dependency": |
||||
The package dependency exists while both packages are running on a single host platform. |
||||
</para> |
||||
<para> |
||||
A build time dependency, however, implies a shift in platforms between the depending package and the depended-on package. |
||||
The meaning of a build time dependency is that to build the depending package we need to be able to run the depended-on's package. |
||||
The depending package's build platform is therefore equal to the depended-on package's host platform. |
||||
Analogously, the depending package's host platform is equal to the depended-on package's target platform. |
||||
</para> |
||||
<para> |
||||
In this manner, given the 3 platforms for one package, we can determine the three platforms for all its transitive dependencies. |
||||
This is the most important guiding principle behind cross-compilation with Nixpkgs, and will be called the <wordasword>sliding window principle</wordasword>. |
||||
</para> |
||||
<title>Specifying Dependencies</title> |
||||
|
||||
<para> |
||||
In this section we explore the relationship between both runtime and |
||||
buildtime dependencies and the 3 Autoconf platforms. |
||||
</para> |
||||
|
||||
<para> |
||||
A runtime dependency between 2 packages implies that between them both the |
||||
host and target platforms match. This is directly implied by the meaning of |
||||
"host platform" and "runtime dependency": The package dependency exists |
||||
while both packages are running on a single host platform. |
||||
</para> |
||||
|
||||
<para> |
||||
A build time dependency, however, implies a shift in platforms between the |
||||
depending package and the depended-on package. The meaning of a build time |
||||
dependency is that to build the depending package we need to be able to run |
||||
the depended-on's package. The depending package's build platform is |
||||
therefore equal to the depended-on package's host platform. Analogously, |
||||
the depending package's host platform is equal to the depended-on package's |
||||
target platform. |
||||
</para> |
||||
|
||||
<para> |
||||
In this manner, given the 3 platforms for one package, we can determine the |
||||
three platforms for all its transitive dependencies. This is the most |
||||
important guiding principle behind cross-compilation with Nixpkgs, and will |
||||
be called the <wordasword>sliding window principle</wordasword>. |
||||
</para> |
||||
|
||||
<para> |
||||
Some examples will probably make this clearer. If a package is being built |
||||
with a <literal>(build, host, target)</literal> platform triple of |
||||
<literal>(foo, bar, bar)</literal>, then its build-time dependencies would |
||||
have a triple of <literal>(foo, foo, bar)</literal>, and <emphasis>those |
||||
packages'</emphasis> build-time dependencies would have triple of |
||||
<literal>(foo, foo, foo)</literal>. In other words, it should take two |
||||
"rounds" of following build-time dependency edges before one reaches a |
||||
fixed point where, by the sliding window principle, the platform triple no |
||||
longer changes. Indeed, this happens with cross compilation, where only |
||||
rounds of native dependencies starting with the second necessarily coincide |
||||
with native packages. |
||||
</para> |
||||
|
||||
<note> |
||||
<para> |
||||
Some examples will probably make this clearer. |
||||
If a package is being built with a <literal>(build, host, target)</literal> platform triple of <literal>(foo, bar, bar)</literal>, then its build-time dependencies would have a triple of <literal>(foo, foo, bar)</literal>, and <emphasis>those packages'</emphasis> build-time dependencies would have triple of <literal>(foo, foo, foo)</literal>. |
||||
In other words, it should take two "rounds" of following build-time dependency edges before one reaches a fixed point where, by the sliding window principle, the platform triple no longer changes. |
||||
Indeed, this happens with cross compilation, where only rounds of native dependencies starting with the second necessarily coincide with native packages. |
||||
The depending package's target platform is unconstrained by the sliding |
||||
window principle, which makes sense in that one can in principle build |
||||
cross compilers targeting arbitrary platforms. |
||||
</para> |
||||
<note><para> |
||||
The depending package's target platform is unconstrained by the sliding window principle, which makes sense in that one can in principle build cross compilers targeting arbitrary platforms. |
||||
</para></note> |
||||
</note> |
||||
|
||||
<para> |
||||
How does this work in practice? Nixpkgs is now structured so that |
||||
build-time dependencies are taken from <varname>buildPackages</varname>, |
||||
whereas run-time dependencies are taken from the top level attribute set. |
||||
For example, <varname>buildPackages.gcc</varname> should be used at build |
||||
time, while <varname>gcc</varname> should be used at run time. Now, for |
||||
most of Nixpkgs's history, there was no <varname>buildPackages</varname>, |
||||
and most packages have not been refactored to use it explicitly. Instead, |
||||
one can use the six (<emphasis>gasp</emphasis>) attributes used for |
||||
specifying dependencies as documented in |
||||
<xref linkend="ssec-stdenv-dependencies"/>. We "splice" together the |
||||
run-time and build-time package sets with <varname>callPackage</varname>, |
||||
and then <varname>mkDerivation</varname> for each of four attributes pulls |
||||
the right derivation out. This splicing can be skipped when not cross |
||||
compiling as the package sets are the same, but is a bit slow for cross |
||||
compiling. Because of this, a best-of-both-worlds solution is in the works |
||||
with no splicing or explicit access of <varname>buildPackages</varname> |
||||
needed. For now, feel free to use either method. |
||||
</para> |
||||
|
||||
<note> |
||||
<para> |
||||
How does this work in practice? Nixpkgs is now structured so that build-time dependencies are taken from <varname>buildPackages</varname>, whereas run-time dependencies are taken from the top level attribute set. |
||||
For example, <varname>buildPackages.gcc</varname> should be used at build time, while <varname>gcc</varname> should be used at run time. |
||||
Now, for most of Nixpkgs's history, there was no <varname>buildPackages</varname>, and most packages have not been refactored to use it explicitly. |
||||
Instead, one can use the six (<emphasis>gasp</emphasis>) attributes used for specifying dependencies as documented in <xref linkend="ssec-stdenv-dependencies"/>. |
||||
We "splice" together the run-time and build-time package sets with <varname>callPackage</varname>, and then <varname>mkDerivation</varname> for each of four attributes pulls the right derivation out. |
||||
This splicing can be skipped when not cross compiling as the package sets are the same, but is a bit slow for cross compiling. |
||||
Because of this, a best-of-both-worlds solution is in the works with no splicing or explicit access of <varname>buildPackages</varname> needed. |
||||
For now, feel free to use either method. |
||||
There is also a "backlink" <varname>targetPackages</varname>, yielding a |
||||
package set whose <varname>buildPackages</varname> is the current package |
||||
set. This is a hack, though, to accommodate compilers with lousy build |
||||
systems. Please do not use this unless you are absolutely sure you are |
||||
packaging such a compiler and there is no other way. |
||||
</para> |
||||
<note><para> |
||||
There is also a "backlink" <varname>targetPackages</varname>, yielding a package set whose <varname>buildPackages</varname> is the current package set. |
||||
This is a hack, though, to accommodate compilers with lousy build systems. |
||||
Please do not use this unless you are absolutely sure you are packaging such a compiler and there is no other way. |
||||
</para></note> |
||||
</note> |
||||
</section> |
||||
|
||||
<section> |
||||
<title>Cross packagaing cookbook</title> |
||||
<para> |
||||
Some frequently problems when packaging for cross compilation are good to just spell and answer. |
||||
Ideally the information above is exhaustive, so this section cannot provide any new information, |
||||
but its ludicrous and cruel to expect everyone to spend effort working through the interaction of many features just to figure out the same answer to the same common problem. |
||||
Feel free to add to this list! |
||||
</para> |
||||
<qandaset> |
||||
<qandaentry> |
||||
<question><para> |
||||
What if my package's build system needs to build a C program to be run under the build environment? |
||||
</para></question> |
||||
<answer><para> |
||||
<programlisting>depsBuildBuild = [ buildPackages.stdenv.cc ];</programlisting> |
||||
Add it to your <function>mkDerivation</function> invocation. |
||||
</para></answer> |
||||
</qandaentry> |
||||
<qandaentry> |
||||
<question><para> |
||||
My package fails to find <command>ar</command>. |
||||
</para></question> |
||||
<answer><para> |
||||
Many packages assume that an unprefixed <command>ar</command> is available, but Nix doesn't provide one. |
||||
It only provides a prefixed one, just as it only does for all the other binutils programs. |
||||
It may be necessary to patch the package to fix the build system to use a prefixed `ar`. |
||||
</para></answer> |
||||
</qandaentry> |
||||
<qandaentry> |
||||
<question><para> |
||||
My package's testsuite needs to run host platform code. |
||||
</para></question> |
||||
<answer><para> |
||||
<programlisting>doCheck = stdenv.hostPlatform != stdenv.buildPlatfrom;</programlisting> |
||||
Add it to your <function>mkDerivation</function> invocation. |
||||
</para></answer> |
||||
</qandaentry> |
||||
</qandaset> |
||||
</section> |
||||
</section> |
||||
<title>Cross packagaing cookbook</title> |
||||
|
||||
<!--============================================================--> |
||||
<para> |
||||
Some frequently problems when packaging for cross compilation are good to |
||||
just spell and answer. Ideally the information above is exhaustive, so this |
||||
section cannot provide any new information, but its ludicrous and cruel to |
||||
expect everyone to spend effort working through the interaction of many |
||||
features just to figure out the same answer to the same common problem. |
||||
Feel free to add to this list! |
||||
</para> |
||||
|
||||
<section xml:id="sec-cross-usage"> |
||||
<qandaset> |
||||
<qandaentry> |
||||
<question> |
||||
<para> |
||||
What if my package's build system needs to build a C program to be run |
||||
under the build environment? |
||||
</para> |
||||
</question> |
||||
<answer> |
||||
<para> |
||||
<programlisting>depsBuildBuild = [ buildPackages.stdenv.cc ];</programlisting> |
||||
Add it to your <function>mkDerivation</function> invocation. |
||||
</para> |
||||
</answer> |
||||
</qandaentry> |
||||
<qandaentry> |
||||
<question> |
||||
<para> |
||||
My package fails to find <command>ar</command>. |
||||
</para> |
||||
</question> |
||||
<answer> |
||||
<para> |
||||
Many packages assume that an unprefixed <command>ar</command> is |
||||
available, but Nix doesn't provide one. It only provides a prefixed one, |
||||
just as it only does for all the other binutils programs. It may be |
||||
necessary to patch the package to fix the build system to use a prefixed |
||||
`ar`. |
||||
</para> |
||||
</answer> |
||||
</qandaentry> |
||||
<qandaentry> |
||||
<question> |
||||
<para> |
||||
My package's testsuite needs to run host platform code. |
||||
</para> |
||||
</question> |
||||
<answer> |
||||
<para> |
||||
<programlisting>doCheck = stdenv.hostPlatform != stdenv.buildPlatfrom;</programlisting> |
||||
Add it to your <function>mkDerivation</function> invocation. |
||||
</para> |
||||
</answer> |
||||
</qandaentry> |
||||
</qandaset> |
||||
</section> |
||||
</section> |
||||
<!--============================================================--> |
||||
<section xml:id="sec-cross-usage"> |
||||
<title>Cross-building packages</title> |
||||
<note><para> |
||||
More information needs to moved from the old wiki, especially <link xlink:href="https://nixos.org/wiki/CrossCompiling" />, for this section. |
||||
</para></note> |
||||
|
||||
<note> |
||||
<para> |
||||
More information needs to moved from the old wiki, especially |
||||
<link xlink:href="https://nixos.org/wiki/CrossCompiling" />, for this |
||||
section. |
||||
</para> |
||||
</note> |
||||
|
||||
<para> |
||||
Nixpkgs can be instantiated with <varname>localSystem</varname> alone, in which case there is no cross compiling and everything is built by and for that system, |
||||
or also with <varname>crossSystem</varname>, in which case packages run on the latter, but all building happens on the former. |
||||
Both parameters take the same schema as the 3 (build, host, and target) platforms defined in the previous section. |
||||
As mentioned above, <literal>lib.systems.examples</literal> has some platforms which are used as arguments for these parameters in practice. |
||||
You can use them programmatically, or on the command line: <programlisting> |
||||
Nixpkgs can be instantiated with <varname>localSystem</varname> alone, in |
||||
which case there is no cross compiling and everything is built by and for |
||||
that system, or also with <varname>crossSystem</varname>, in which case |
||||
packages run on the latter, but all building happens on the former. Both |
||||
parameters take the same schema as the 3 (build, host, and target) platforms |
||||
defined in the previous section. As mentioned above, |
||||
<literal>lib.systems.examples</literal> has some platforms which are used as |
||||
arguments for these parameters in practice. You can use them |
||||
programmatically, or on the command line: |
||||
<programlisting> |
||||
nix-build <nixpkgs> --arg crossSystem '(import <nixpkgs/lib>).systems.examples.fooBarBaz' -A whatever</programlisting> |
||||
</para> |
||||
|
||||
<note> |
||||
<para> |
||||
Eventually we would like to make these platform examples an unnecessary convenience so that <programlisting> |
||||
<para> |
||||
Eventually we would like to make these platform examples an unnecessary |
||||
convenience so that |
||||
<programlisting> |
||||
nix-build <nixpkgs> --arg crossSystem.config '<arch>-<os>-<vendor>-<abi>' -A whatever</programlisting> |
||||
works in the vast majority of cases. |
||||
The problem today is dependencies on other sorts of configuration which aren't given proper defaults. |
||||
We rely on the examples to crudely to set those configuration parameters in some vaguely sane manner on the users behalf. |
||||
Issue <link xlink:href="https://github.com/NixOS/nixpkgs/issues/34274">#34274</link> tracks this inconvenience along with its root cause in crufty configuration options. |
||||
</para> |
||||
works in the vast majority of cases. The problem today is dependencies on |
||||
other sorts of configuration which aren't given proper defaults. We rely on |
||||
the examples to crudely to set those configuration parameters in some |
||||
vaguely sane manner on the users behalf. Issue |
||||
<link xlink:href="https://github.com/NixOS/nixpkgs/issues/34274">#34274</link> |
||||
tracks this inconvenience along with its root cause in crufty configuration |
||||
options. |
||||
</para> |
||||
</note> |
||||
|
||||
<para> |
||||
While one is free to pass both parameters in full, there's a lot of logic to fill in missing fields. |
||||
As discussed in the previous section, only one of <varname>system</varname>, <varname>config</varname>, and <varname>parsed</varname> is needed to infer the other two. |
||||
Additionally, <varname>libc</varname> will be inferred from <varname>parse</varname>. |
||||
Finally, <literal>localSystem.system</literal> is also <emphasis>impurely</emphasis> inferred based on the platform evaluation occurs. |
||||
This means it is often not necessary to pass <varname>localSystem</varname> at all, as in the command-line example in the previous paragraph. |
||||
While one is free to pass both parameters in full, there's a lot of logic to |
||||
fill in missing fields. As discussed in the previous section, only one of |
||||
<varname>system</varname>, <varname>config</varname>, and |
||||
<varname>parsed</varname> is needed to infer the other two. Additionally, |
||||
<varname>libc</varname> will be inferred from <varname>parse</varname>. |
||||
Finally, <literal>localSystem.system</literal> is also |
||||
<emphasis>impurely</emphasis> inferred based on the platform evaluation |
||||
occurs. This means it is often not necessary to pass |
||||
<varname>localSystem</varname> at all, as in the command-line example in the |
||||
previous paragraph. |
||||
</para> |
||||
|
||||
<note> |
||||
<para> |
||||
Many sources (manual, wiki, etc) probably mention passing <varname>system</varname>, <varname>platform</varname>, along with the optional <varname>crossSystem</varname> to nixpkgs: |
||||
<literal>import <nixpkgs> { system = ..; platform = ..; crossSystem = ..; }</literal>. |
||||
Passing those two instead of <varname>localSystem</varname> is still supported for compatibility, but is discouraged. |
||||
Indeed, much of the inference we do for these parameters is motivated by compatibility as much as convenience. |
||||
</para> |
||||
<para> |
||||
Many sources (manual, wiki, etc) probably mention passing |
||||
<varname>system</varname>, <varname>platform</varname>, along with the |
||||
optional <varname>crossSystem</varname> to nixpkgs: <literal>import |
||||
<nixpkgs> { system = ..; platform = ..; crossSystem = ..; |
||||
}</literal>. Passing those two instead of <varname>localSystem</varname> is |
||||
still supported for compatibility, but is discouraged. Indeed, much of the |
||||
inference we do for these parameters is motivated by compatibility as much |
||||
as convenience. |
||||
</para> |
||||
</note> |
||||
|
||||
<para> |
||||
One would think that <varname>localSystem</varname> and <varname>crossSystem</varname> overlap horribly with the three <varname>*Platforms</varname> (<varname>buildPlatform</varname>, <varname>hostPlatform,</varname> and <varname>targetPlatform</varname>; see <varname>stage.nix</varname> or the manual). |
||||
Actually, those identifiers are purposefully not used here to draw a subtle but important distinction: |
||||
While the granularity of having 3 platforms is necessary to properly *build* packages, it is overkill for specifying the user's *intent* when making a build plan or package set. |
||||
A simple "build vs deploy" dichotomy is adequate: the sliding window principle described in the previous section shows how to interpolate between the these two "end points" to get the 3 platform triple for each bootstrapping stage. |
||||
That means for any package a given package set, even those not bound on the top level but only reachable via dependencies or <varname>buildPackages</varname>, the three platforms will be defined as one of <varname>localSystem</varname> or <varname>crossSystem</varname>, with the former replacing the latter as one traverses build-time dependencies. |
||||
A last simple difference then is <varname>crossSystem</varname> should be null when one doesn't want to cross-compile, while the <varname>*Platform</varname>s are always non-null. |
||||
<varname>localSystem</varname> is always non-null. |
||||
One would think that <varname>localSystem</varname> and |
||||
<varname>crossSystem</varname> overlap horribly with the three |
||||
<varname>*Platforms</varname> (<varname>buildPlatform</varname>, |
||||
<varname>hostPlatform,</varname> and <varname>targetPlatform</varname>; see |
||||
<varname>stage.nix</varname> or the manual). Actually, those identifiers are |
||||
purposefully not used here to draw a subtle but important distinction: While |
||||
the granularity of having 3 platforms is necessary to properly *build* |
||||
packages, it is overkill for specifying the user's *intent* when making a |
||||
build plan or package set. A simple "build vs deploy" dichotomy is adequate: |
||||
the sliding window principle described in the previous section shows how to |
||||
interpolate between the these two "end points" to get the 3 platform triple |
||||
for each bootstrapping stage. That means for any package a given package |
||||
set, even those not bound on the top level but only reachable via |
||||
dependencies or <varname>buildPackages</varname>, the three platforms will |
||||
be defined as one of <varname>localSystem</varname> or |
||||
<varname>crossSystem</varname>, with the former replacing the latter as one |
||||
traverses build-time dependencies. A last simple difference then is |
||||
<varname>crossSystem</varname> should be null when one doesn't want to |
||||
cross-compile, while the <varname>*Platform</varname>s are always non-null. |
||||
<varname>localSystem</varname> is always non-null. |
||||
</para> |
||||
</section> |
||||
|
||||
</section> |
||||
<!--============================================================--> |
||||
|
||||
<section xml:id="sec-cross-infra"> |
||||
<section xml:id="sec-cross-infra"> |
||||
<title>Cross-compilation infrastructure</title> |
||||
<para>To be written.</para> |
||||
<note><para> |
||||
If one explores nixpkgs, they will see derivations with names like <literal>gccCross</literal>. |
||||
Such <literal>*Cross</literal> derivations is a holdover from before we properly distinguished between the host and target platforms |
||||
—the derivation with "Cross" in the name covered the <literal>build = host != target</literal> case, while the other covered the <literal>host = target</literal>, with build platform the same or not based on whether one was using its <literal>.nativeDrv</literal> or <literal>.crossDrv</literal>. |
||||
This ugliness will disappear soon. |
||||
</para></note> |
||||
</section> |
||||
|
||||
<para> |
||||
To be written. |
||||
</para> |
||||
|
||||
<note> |
||||
<para> |
||||
If one explores nixpkgs, they will see derivations with names like |
||||
<literal>gccCross</literal>. Such <literal>*Cross</literal> derivations is |
||||
a holdover from before we properly distinguished between the host and |
||||
target platforms —the derivation with "Cross" in the name covered the |
||||
<literal>build = host != target</literal> case, while the other covered the |
||||
<literal>host = target</literal>, with build platform the same or not based |
||||
on whether one was using its <literal>.nativeDrv</literal> or |
||||
<literal>.crossDrv</literal>. This ugliness will disappear soon. |
||||
</para> |
||||
</note> |
||||
</section> |
||||
</chapter> |
||||
|
File diff suppressed because it is too large
Load Diff
@ -0,0 +1,185 @@ |
||||
# User's Guide to Emscripten in Nixpkgs |
||||
|
||||
[Emscripten](https://github.com/kripken/emscripten): An LLVM-to-JavaScript Compiler |
||||
|
||||
This section of the manual covers how to use `emscripten` in nixpkgs. |
||||
|
||||
Minimal requirements: |
||||
|
||||
* nix |
||||
* nixpkgs |
||||
|
||||
Modes of use of `emscripten`: |
||||
|
||||
* **Imperative usage** (on the command line): |
||||
|
||||
If you want to work with `emcc`, `emconfigure` and `emmake` as you are used to from Ubuntu and similar distributions you can use these commands: |
||||
|
||||
* `nix-env -i emscripten` |
||||
* `nix-shell -p emscripten` |
||||
|
||||
* **Declarative usage**: |
||||
|
||||
This mode is far more power full since this makes use of `nix` for dependency management of emscripten libraries and targets by using the `mkDerivation` which is implemented by `pkgs.emscriptenStdenv` and `pkgs.buildEmscriptenPackage`. The source for the packages is in `pkgs/top-level/emscripten-packages.nix` and the abstraction behind it in `pkgs/development/em-modules/generic/default.nix`. |
||||
* build and install all packages: |
||||
* `nix-env -iA emscriptenPackages` |
||||
|
||||
* dev-shell for zlib implementation hacking: |
||||
* `nix-shell -A emscriptenPackages.zlib` |
||||
|
||||
|
||||
## Imperative usage |
||||
|
||||
A few things to note: |
||||
|
||||
* `export EMCC_DEBUG=2` is nice for debugging |
||||
* `~/.emscripten`, the build artifact cache sometimes creates issues and needs to be removed from time to time |
||||
|
||||
|
||||
## Declarative usage |
||||
|
||||
Let's see two different examples from `pkgs/top-level/emscripten-packages.nix`: |
||||
|
||||
* `pkgs.zlib.override` |
||||
* `pkgs.buildEmscriptenPackage` |
||||
|
||||
Both are interesting concepts. |
||||
|
||||
A special requirement of the `pkgs.buildEmscriptenPackage` is the `doCheck = true` is a default meaning that each emscriptenPackage requires a `checkPhase` implemented. |
||||
|
||||
* Use `export EMCC_DEBUG=2` from within a emscriptenPackage's `phase` to get more detailed debug output what is going wrong. |
||||
* ~/.emscripten cache is requiring us to set `HOME=$TMPDIR` in individual phases. This makes compilation slower but also makes it more deterministic. |
||||
|
||||
### Usage 1: pkgs.zlib.override |
||||
|
||||
This example uses `zlib` from nixpkgs but instead of compiling **C** to **ELF** it compiles **C** to **JS** since we were using `pkgs.zlib.override` and changed stdenv to `pkgs.emscriptenStdenv`. A few adaptions and hacks were set in place to make it working. One advantage is that when `pkgs.zlib` is updated, it will automatically update this package as well. However, this can also be the downside... |
||||
|
||||
See the `zlib` example: |
||||
|
||||
zlib = (pkgs.zlib.override { |
||||
stdenv = pkgs.emscriptenStdenv; |
||||
}).overrideDerivation |
||||
(old: rec { |
||||
buildInputs = old.buildInputs ++ [ pkgconfig ]; |
||||
# we need to reset this setting! |
||||
NIX_CFLAGS_COMPILE=""; |
||||
configurePhase = '' |
||||
# FIXME: Some tests require writing at $HOME |
||||
HOME=$TMPDIR |
||||
runHook preConfigure |
||||
|
||||
#export EMCC_DEBUG=2 |
||||
emconfigure ./configure --prefix=$out --shared |
||||
|
||||
runHook postConfigure |
||||
''; |
||||
dontStrip = true; |
||||
outputs = [ "out" ]; |
||||
buildPhase = '' |
||||
emmake make |
||||
''; |
||||
installPhase = '' |
||||
emmake make install |
||||
''; |
||||
checkPhase = '' |
||||
echo "================= testing zlib using node =================" |
||||
|
||||
echo "Compiling a custom test" |
||||
set -x |
||||
emcc -O2 -s EMULATE_FUNCTION_POINTER_CASTS=1 test/example.c -DZ_SOLO \ |
||||
libz.so.${old.version} -I . -o example.js |
||||
|
||||
echo "Using node to execute the test" |
||||
${pkgs.nodejs}/bin/node ./example.js |
||||
|
||||
set +x |
||||
if [ $? -ne 0 ]; then |
||||
echo "test failed for some reason" |
||||
exit 1; |
||||
else |
||||
echo "it seems to work! very good." |
||||
fi |
||||
echo "================= /testing zlib using node =================" |
||||
''; |
||||
|
||||
postPatch = pkgs.stdenv.lib.optionalString pkgs.stdenv.isDarwin '' |
||||
substituteInPlace configure \ |
||||
--replace '/usr/bin/libtool' 'ar' \ |
||||
--replace 'AR="libtool"' 'AR="ar"' \ |
||||
--replace 'ARFLAGS="-o"' 'ARFLAGS="-r"' |
||||
''; |
||||
}); |
||||
|
||||
### Usage 2: pkgs.buildEmscriptenPackage |
||||
|
||||
This `xmlmirror` example features a emscriptenPackage which is defined completely from this context and no `pkgs.zlib.override` is used. |
||||
|
||||
xmlmirror = pkgs.buildEmscriptenPackage rec { |
||||
name = "xmlmirror"; |
||||
|
||||
buildInputs = [ pkgconfig autoconf automake libtool gnumake libxml2 nodejs openjdk json_c ]; |
||||
nativeBuildInputs = [ pkgconfig zlib ]; |
||||
|
||||
src = pkgs.fetchgit { |
||||
url = "https://gitlab.com/odfplugfest/xmlmirror.git"; |
||||
rev = "4fd7e86f7c9526b8f4c1733e5c8b45175860a8fd"; |
||||
sha256 = "1jasdqnbdnb83wbcnyrp32f36w3xwhwp0wq8lwwmhqagxrij1r4b"; |
||||
}; |
||||
|
||||
configurePhase = '' |
||||
rm -f fastXmlLint.js* |
||||
# a fix for ERROR:root:For asm.js, TOTAL_MEMORY must be a multiple of 16MB, was 234217728 |
||||
# https://gitlab.com/odfplugfest/xmlmirror/issues/8 |
||||
sed -e "s/TOTAL_MEMORY=234217728/TOTAL_MEMORY=268435456/g" -i Makefile.emEnv |
||||
# https://github.com/kripken/emscripten/issues/6344 |
||||
# https://gitlab.com/odfplugfest/xmlmirror/issues/9 |
||||
sed -e "s/\$(JSONC_LDFLAGS) \$(ZLIB_LDFLAGS) \$(LIBXML20_LDFLAGS)/\$(JSONC_LDFLAGS) \$(LIBXML20_LDFLAGS) \$(ZLIB_LDFLAGS) /g" -i Makefile.emEnv |
||||
# https://gitlab.com/odfplugfest/xmlmirror/issues/11 |
||||
sed -e "s/-o fastXmlLint.js/-s EXTRA_EXPORTED_RUNTIME_METHODS='[\"ccall\", \"cwrap\"]' -o fastXmlLint.js/g" -i Makefile.emEnv |
||||
''; |
||||
|
||||
buildPhase = '' |
||||
HOME=$TMPDIR |
||||
make -f Makefile.emEnv |
||||
''; |
||||
|
||||
outputs = [ "out" "doc" ]; |
||||
|
||||
installPhase = '' |
||||
mkdir -p $out/share |
||||
mkdir -p $doc/share/${name} |
||||
|
||||
cp Demo* $out/share |
||||
cp -R codemirror-5.12 $out/share |
||||
cp fastXmlLint.js* $out/share |
||||
cp *.xsd $out/share |
||||
cp *.js $out/share |
||||
cp *.xhtml $out/share |
||||
cp *.html $out/share |
||||
cp *.json $out/share |
||||
cp *.rng $out/share |
||||
cp README.md $doc/share/${name} |
||||
''; |
||||
checkPhase = '' |
||||
|
||||
''; |
||||
}; |
||||
|
||||
### Declarative debugging |
||||
|
||||
Use `nix-shell -I nixpkgs=/some/dir/nixpkgs -A emscriptenPackages.libz` and from there you can go trough the individual steps. This makes it easy to build a good `unit test` or list the files of the project. |
||||
|
||||
1. `nix-shell -I nixpkgs=/some/dir/nixpkgs -A emscriptenPackages.libz` |
||||
2. `cd /tmp/` |
||||
3. `unpackPhase` |
||||
4. cd libz-1.2.3 |
||||
5. `configurePhase` |
||||
6. `buildPhase` |
||||
7. ... happy hacking... |
||||
|
||||
## Summary |
||||
|
||||
Using this toolchain makes it easy to leverage `nix` from NixOS, MacOSX or even Windows (WSL+ubuntu+nix). This toolchain is reproducible, behaves like the rest of the packages from nixpkgs and contains a set of well working examples to learn and adapt from. |
||||
|
||||
If in trouble, ask the maintainers. |
||||
|
@ -0,0 +1,39 @@ |
||||
Idris packages |
||||
============== |
||||
|
||||
This directory contains build rules for idris packages. In addition, |
||||
it contains several functions to build and compose those packages. |
||||
Everything is exposed to the user via the `idrisPackages` attribute. |
||||
|
||||
callPackage |
||||
------------ |
||||
|
||||
This is like the normal nixpkgs callPackage function, specialized to |
||||
idris packages. |
||||
|
||||
builtins |
||||
--------- |
||||
|
||||
This is a list of all of the libraries that come packaged with Idris |
||||
itself. |
||||
|
||||
build-idris-package |
||||
-------------------- |
||||
|
||||
A function to build an idris package. Its sole argument is a set like |
||||
you might pass to `stdenv.mkDerivation`, except `build-idris-package` |
||||
sets several attributes for you. See `build-idris-package.nix` for |
||||
details. |
||||
|
||||
build-builtin-package |
||||
---------------------- |
||||
|
||||
A version of `build-idris-package` specialized to builtin libraries. |
||||
Mostly for internal use. |
||||
|
||||
with-packages |
||||
------------- |
||||
|
||||
Bundle idris together with a list of packages. Because idris currently |
||||
only supports a single directory in its library path, you must include |
||||
all desired libraries here, including `prelude` and `base`. |
@ -1,35 +1,31 @@ |
||||
<chapter xmlns="http://docbook.org/ns/docbook" |
||||
xmlns:xi="http://www.w3.org/2001/XInclude" |
||||
xml:id="chap-language-support"> |
||||
|
||||
<title>Support for specific programming languages and frameworks</title> |
||||
|
||||
<para>The <link linkend="chap-stdenv">standard build |
||||
environment</link> makes it easy to build typical Autotools-based |
||||
packages with very little code. Any other kind of package can be |
||||
accomodated by overriding the appropriate phases of |
||||
<literal>stdenv</literal>. However, there are specialised functions |
||||
in Nixpkgs to easily build packages for other programming languages, |
||||
such as Perl or Haskell. These are described in this chapter.</para> |
||||
|
||||
|
||||
<xi:include href="beam.xml" /> |
||||
<xi:include href="bower.xml" /> |
||||
<xi:include href="coq.xml" /> |
||||
<xi:include href="go.xml" /> |
||||
<xi:include href="haskell.xml" /> |
||||
<xi:include href="idris.xml" /> <!-- generated from ../../pkgs/development/idris-modules/README.md --> |
||||
<xi:include href="java.xml" /> |
||||
<xi:include href="lua.xml" /> |
||||
<xi:include href="node.xml" /> <!-- generated from ../../pkgs/development/node-packages/README.md --> |
||||
<xi:include href="perl.xml" /> |
||||
<xi:include href="python.xml" /> |
||||
<xi:include href="qt.xml" /> |
||||
<xi:include href="r.xml" /> <!-- generated from ../../pkgs/development/r-modules/README.md --> |
||||
<xi:include href="ruby.xml" /> |
||||
<xi:include href="rust.xml" /> |
||||
<xi:include href="texlive.xml" /> |
||||
<xi:include href="vim.xml" /> |
||||
|
||||
|
||||
<title>Support for specific programming languages and frameworks</title> |
||||
<para> |
||||
The <link linkend="chap-stdenv">standard build environment</link> makes it |
||||
easy to build typical Autotools-based packages with very little code. Any |
||||
other kind of package can be accomodated by overriding the appropriate phases |
||||
of <literal>stdenv</literal>. However, there are specialised functions in |
||||
Nixpkgs to easily build packages for other programming languages, such as |
||||
Perl or Haskell. These are described in this chapter. |
||||
</para> |
||||
<xi:include href="beam.xml" /> |
||||
<xi:include href="bower.xml" /> |
||||
<xi:include href="coq.xml" /> |
||||
<xi:include href="go.xml" /> |
||||
<xi:include href="haskell.section.xml" /> |
||||
<xi:include href="idris.section.xml" /> |
||||
<xi:include href="java.xml" /> |
||||
<xi:include href="lua.xml" /> |
||||
<xi:include href="node.section.xml" /> |
||||
<xi:include href="perl.xml" /> |
||||
<xi:include href="python.section.xml" /> |
||||
<xi:include href="qt.xml" /> |
||||
<xi:include href="r.section.xml" /> |
||||
<xi:include href="ruby.xml" /> |
||||
<xi:include href="rust.section.xml" /> |
||||
<xi:include href="texlive.xml" /> |
||||
<xi:include href="vim.section.xml" /> |
||||
<xi:include href="emscripten.section.xml" /> |
||||
</chapter> |
||||
|
@ -0,0 +1,51 @@ |
||||
Node.js packages |
||||
================ |
||||
The `pkgs/development/node-packages` folder contains a generated collection of |
||||
[NPM packages](https://npmjs.com/) that can be installed with the Nix package |
||||
manager. |
||||
|
||||
As a rule of thumb, the package set should only provide *end user* software |
||||
packages, such as command-line utilities. Libraries should only be added to the |
||||
package set if there is a non-NPM package that requires it. |
||||
|
||||
When it is desired to use NPM libraries in a development project, use the |
||||
`node2nix` generator directly on the `package.json` configuration file of the |
||||
project. |
||||
|
||||
The package set also provides support for multiple Node.js versions. The policy |
||||
is that a new package should be added to the collection for the latest stable LTS |
||||
release (which is currently 6.x), unless there is an explicit reason to support |
||||
a different release. |
||||
|
||||
If your package uses native addons, you need to examine what kind of native |
||||
build system it uses. Here are some examples: |
||||
|
||||
* `node-gyp` |
||||
* `node-gyp-builder` |
||||
* `node-pre-gyp` |
||||
|
||||
After you have identified the correct system, you need to override your package |
||||
expression while adding in build system as a build input. For example, `dat` |
||||
requires `node-gyp-build`, so we override its expression in `default-v6.nix`: |
||||
|
||||
```nix |
||||
dat = nodePackages.dat.override (oldAttrs: { |
||||
buildInputs = oldAttrs.buildInputs ++ [ nodePackages.node-gyp-build ]; |
||||
}); |
||||
``` |
||||
|
||||
To add a package from NPM to nixpkgs: |
||||
|
||||
1. Modify `pkgs/development/node-packages/node-packages-v6.json` to add, update |
||||
or remove package entries. (Or `pkgs/development/node-packages/node-packages-v4.json` |
||||
for packages depending on Node.js 4.x) |
||||
2. Run the script: `(cd pkgs/development/node-packages && ./generate.sh)`. |
||||
3. Build your new package to test your changes: |
||||
`cd /path/to/nixpkgs && nix-build -A nodePackages.<new-or-updated-package>`. |
||||
To build against a specific Node.js version (e.g. 4.x): |
||||
`nix-build -A nodePackages_4_x.<new-or-updated-package>` |
||||
4. Add and commit all modified and generated files. |
||||
|
||||
For more information about the generation process, consult the |
||||
[README.md](https://github.com/svanderburg/node2nix) file of the `node2nix` |
||||
tool. |
@ -0,0 +1,120 @@ |
||||
R packages |
||||
========== |
||||
|
||||
## Installation |
||||
|
||||
Define an environment for R that contains all the libraries that you'd like to |
||||
use by adding the following snippet to your $HOME/.config/nixpkgs/config.nix file: |
||||
|
||||
```nix |
||||
{ |
||||
packageOverrides = super: let self = super.pkgs; in |
||||
{ |
||||
|
||||
rEnv = super.rWrapper.override { |
||||
packages = with self.rPackages; [ |
||||
devtools |
||||
ggplot2 |
||||
reshape2 |
||||
yaml |
||||
optparse |
||||
]; |
||||
}; |
||||
}; |
||||
} |
||||
``` |
||||
|
||||
Then you can use `nix-env -f "<nixpkgs>" -iA rEnv` to install it into your user |
||||
profile. The set of available libraries can be discovered by running the |
||||
command `nix-env -f "<nixpkgs>" -qaP -A rPackages`. The first column from that |
||||
output is the name that has to be passed to rWrapper in the code snipped above. |
||||
|
||||
However, if you'd like to add a file to your project source to make the |
||||
environment available for other contributors, you can create a `default.nix` |
||||
file like so: |
||||
```nix |
||||
let |
||||
pkgs = import <nixpkgs> {}; |
||||
stdenv = pkgs.stdenv; |
||||
in with pkgs; { |
||||
myProject = stdenv.mkDerivation { |
||||
name = "myProject"; |
||||
version = "1"; |
||||
src = if pkgs.lib.inNixShell then null else nix; |
||||
|
||||
buildInputs = with rPackages; [ |
||||
R |
||||
ggplot2 |
||||
knitr |
||||
]; |
||||
}; |
||||
} |
||||
``` |
||||
and then run `nix-shell .` to be dropped into a shell with those packages |
||||
available. |
||||
|
||||
## RStudio |
||||
|
||||
RStudio uses a standard set of packages and ignores any custom R |
||||
environments or installed packages you may have. To create a custom |
||||
environment, see `rstudioWrapper`, which functions similarly to |
||||
`rWrapper`: |
||||
|
||||
```nix |
||||
{ |
||||
packageOverrides = super: let self = super.pkgs; in |
||||
{ |
||||
|
||||
rstudioEnv = super.rstudioWrapper.override { |
||||
packages = with self.rPackages; [ |
||||
dplyr |
||||
ggplot2 |
||||
reshape2 |
||||
]; |
||||
}; |
||||
}; |
||||
} |
||||
``` |
||||
|
||||
Then like above, `nix-env -f "<nixpkgs>" -iA rstudioEnv` will install |
||||
this into your user profile. |
||||
|
||||
Alternatively, you can create a self-contained `shell.nix` without the need to |
||||
modify any configuration files: |
||||
|
||||
```nix |
||||
{ pkgs ? import <nixpkgs> {} |
||||
}: |
||||
|
||||
pkgs.rstudioWrapper.override { |
||||
packages = with pkgs.rPackages; [ dplyr ggplot2 reshape2 ]; |
||||
} |
||||
|
||||
``` |
||||
|
||||
Executing `nix-shell` will then drop you into an environment equivalent to the |
||||
one above. If you need additional packages just add them to the list and |
||||
re-enter the shell. |
||||
|
||||
## Updating the package set |
||||
|
||||
```bash |
||||
nix-shell generate-shell.nix |
||||
|
||||
Rscript generate-r-packages.R cran > cran-packages.nix.new |
||||
mv cran-packages.nix.new cran-packages.nix |
||||
|
||||
Rscript generate-r-packages.R bioc > bioc-packages.nix.new |
||||
mv bioc-packages.nix.new bioc-packages.nix |
||||
``` |
||||
|
||||
`generate-r-packages.R <repo>` reads `<repo>-packages.nix`, therefor the renaming. |
||||
|
||||
|
||||
## Testing if the Nix-expression could be evaluated |
||||
|
||||
```bash |
||||
nix-build test-evaluation.nix --dry-run |
||||
``` |
||||
|
||||
If this exits fine, the expression is ok. If not, you have to edit `default.nix` |
@ -1,29 +1,24 @@ |
||||
<book xmlns="http://docbook.org/ns/docbook" |
||||
xmlns:xi="http://www.w3.org/2001/XInclude"> |
||||
|
||||
<info> |
||||
|
||||
<title>Nixpkgs Contributors Guide</title> |
||||
|
||||
<subtitle>Version <xi:include href=".version" parse="text" /></subtitle> |
||||
|
||||
</info> |
||||
|
||||
<xi:include href="introduction.xml" /> |
||||
<xi:include href="quick-start.xml" /> |
||||
<xi:include href="stdenv.xml" /> |
||||
<xi:include href="multiple-output.xml" /> |
||||
<xi:include href="cross-compilation.xml" /> |
||||
<xi:include href="configuration.xml" /> |
||||
<xi:include href="functions.xml" /> |
||||
<xi:include href="meta.xml" /> |
||||
<xi:include href="languages-frameworks/index.xml" /> |
||||
<xi:include href="platform-notes.xml" /> |
||||
<xi:include href="package-notes.xml" /> |
||||
<xi:include href="overlays.xml" /> |
||||
<xi:include href="coding-conventions.xml" /> |
||||
<xi:include href="submitting-changes.xml" /> |
||||
<xi:include href="reviewing-contributions.xml" /> |
||||
<xi:include href="contributing.xml" /> |
||||
|
||||
<info> |
||||
<title>Nixpkgs Contributors Guide</title> |
||||
<subtitle>Version <xi:include href=".version" parse="text" /> |
||||
</subtitle> |
||||
</info> |
||||
<xi:include href="introduction.chapter.xml" /> |
||||
<xi:include href="quick-start.xml" /> |
||||
<xi:include href="stdenv.xml" /> |
||||
<xi:include href="multiple-output.xml" /> |
||||
<xi:include href="cross-compilation.xml" /> |
||||
<xi:include href="configuration.xml" /> |
||||
<xi:include href="functions.xml" /> |
||||
<xi:include href="meta.xml" /> |
||||
<xi:include href="languages-frameworks/index.xml" /> |
||||
<xi:include href="platform-notes.xml" /> |
||||
<xi:include href="package-notes.xml" /> |
||||
<xi:include href="overlays.xml" /> |
||||
<xi:include href="coding-conventions.xml" /> |
||||
<xi:include href="submitting-changes.xml" /> |
||||
<xi:include href="reviewing-contributions.xml" /> |
||||
<xi:include href="contributing.xml" /> |
||||
</book> |
||||
|
@ -0,0 +1,9 @@ |
||||
.docbook .xref img[src^=images\/callouts\/], |
||||
.screen img, |
||||
.programlisting img { |
||||
width: 1em; |
||||
} |
||||
|
||||
.calloutlist img { |
||||
width: 1.5em; |
||||
} |
File diff suppressed because it is too large
Load Diff
@ -1,223 +1,219 @@ |
||||
<chapter xmlns="http://docbook.org/ns/docbook" |
||||
xmlns:xlink="http://www.w3.org/1999/xlink" |
||||
xml:id="chap-quick-start"> |
||||
|
||||
<title>Quick Start to Adding a Package</title> |
||||
|
||||
<para>To add a package to Nixpkgs: |
||||
|
||||
<orderedlist> |
||||
|
||||
<listitem> |
||||
<para>Checkout the Nixpkgs source tree: |
||||
|
||||
<title>Quick Start to Adding a Package</title> |
||||
<para> |
||||
To add a package to Nixpkgs: |
||||
<orderedlist> |
||||
<listitem> |
||||
<para> |
||||
Checkout the Nixpkgs source tree: |
||||
<screen> |
||||
$ git clone git://github.com/NixOS/nixpkgs.git |
||||
$ cd nixpkgs</screen> |
||||
|
||||
</para> |
||||
</listitem> |
||||
|
||||
<listitem> |
||||
<para>Find a good place in the Nixpkgs tree to add the Nix |
||||
expression for your package. For instance, a library package |
||||
typically goes into |
||||
<filename>pkgs/development/libraries/<replaceable>pkgname</replaceable></filename>, |
||||
while a web browser goes into |
||||
<filename>pkgs/applications/networking/browsers/<replaceable>pkgname</replaceable></filename>. |
||||
See <xref linkend="sec-organisation" /> for some hints on the tree |
||||
organisation. Create a directory for your package, e.g. |
||||
|
||||
</listitem> |
||||
<listitem> |
||||
<para> |
||||
Find a good place in the Nixpkgs tree to add the Nix expression for your |
||||
package. For instance, a library package typically goes into |
||||
<filename>pkgs/development/libraries/<replaceable>pkgname</replaceable></filename>, |
||||
while a web browser goes into |
||||
<filename>pkgs/applications/networking/browsers/<replaceable>pkgname</replaceable></filename>. |
||||
See <xref linkend="sec-organisation" /> for some hints on the tree |
||||
organisation. Create a directory for your package, e.g. |
||||
<screen> |
||||
$ mkdir pkgs/development/libraries/libfoo</screen> |
||||
|
||||
</para> |
||||
</listitem> |
||||
|
||||
<listitem> |
||||
<para>In the package directory, create a Nix expression — a piece |
||||
of code that describes how to build the package. In this case, it |
||||
should be a <emphasis>function</emphasis> that is called with the |
||||
package dependencies as arguments, and returns a build of the |
||||
package in the Nix store. The expression should usually be called |
||||
<filename>default.nix</filename>. |
||||
|
||||
</listitem> |
||||
<listitem> |
||||
<para> |
||||
In the package directory, create a Nix expression — a piece of code that |
||||
describes how to build the package. In this case, it should be a |
||||
<emphasis>function</emphasis> that is called with the package dependencies |
||||
as arguments, and returns a build of the package in the Nix store. The |
||||
expression should usually be called <filename>default.nix</filename>. |
||||
<screen> |
||||
$ emacs pkgs/development/libraries/libfoo/default.nix |
||||
$ git add pkgs/development/libraries/libfoo/default.nix</screen> |
||||
|
||||
</para> |
||||
|
||||
<para>You can have a look at the existing Nix expressions under |
||||
<filename>pkgs/</filename> to see how it’s done. Here are some |
||||
good ones: |
||||
|
||||
<itemizedlist> |
||||
|
||||
<listitem> |
||||
<para>GNU Hello: <link |
||||
<para> |
||||
You can have a look at the existing Nix expressions under |
||||
<filename>pkgs/</filename> to see how it’s done. Here are some good |
||||
ones: |
||||
<itemizedlist> |
||||
<listitem> |
||||
<para> |
||||
GNU Hello: |
||||
<link |
||||
xlink:href="https://github.com/NixOS/nixpkgs/blob/master/pkgs/applications/misc/hello/default.nix"><filename>pkgs/applications/misc/hello/default.nix</filename></link>. |
||||
Trivial package, which specifies some <varname>meta</varname> |
||||
attributes which is good practice.</para> |
||||
</listitem> |
||||
|
||||
<listitem> |
||||
<para>GNU cpio: <link |
||||
Trivial package, which specifies some <varname>meta</varname> |
||||
attributes which is good practice. |
||||
</para> |
||||
</listitem> |
||||
<listitem> |
||||
<para> |
||||
GNU cpio: |
||||
<link |
||||
xlink:href="https://github.com/NixOS/nixpkgs/blob/master/pkgs/tools/archivers/cpio/default.nix"><filename>pkgs/tools/archivers/cpio/default.nix</filename></link>. |
||||
Also a simple package. The generic builder in |
||||
<varname>stdenv</varname> does everything for you. It has |
||||
no dependencies beyond <varname>stdenv</varname>.</para> |
||||
</listitem> |
||||
|
||||
<listitem> |
||||
<para>GNU Multiple Precision arithmetic library (GMP): <link |
||||
Also a simple package. The generic builder in <varname>stdenv</varname> |
||||
does everything for you. It has no dependencies beyond |
||||
<varname>stdenv</varname>. |
||||
</para> |
||||
</listitem> |
||||
<listitem> |
||||
<para> |
||||
GNU Multiple Precision arithmetic library (GMP): |
||||
<link |
||||
xlink:href="https://github.com/NixOS/nixpkgs/blob/master/pkgs/development/libraries/gmp/5.1.x.nix"><filename>pkgs/development/libraries/gmp/5.1.x.nix</filename></link>. |
||||
Also done by the generic builder, but has a dependency on |
||||
<varname>m4</varname>.</para> |
||||
</listitem> |
||||
|
||||
<listitem> |
||||
<para>Pan, a GTK-based newsreader: <link |
||||
Also done by the generic builder, but has a dependency on |
||||
<varname>m4</varname>. |
||||
</para> |
||||
</listitem> |
||||
<listitem> |
||||
<para> |
||||
Pan, a GTK-based newsreader: |
||||
<link |
||||
xlink:href="https://github.com/NixOS/nixpkgs/blob/master/pkgs/applications/networking/newsreaders/pan/default.nix"><filename>pkgs/applications/networking/newsreaders/pan/default.nix</filename></link>. |
||||
Has an optional dependency on <varname>gtkspell</varname>, |
||||
which is only built if <varname>spellCheck</varname> is |
||||
<literal>true</literal>.</para> |
||||
</listitem> |
||||
|
||||
<listitem> |
||||
<para>Apache HTTPD: <link |
||||
Has an optional dependency on <varname>gtkspell</varname>, which is |
||||
only built if <varname>spellCheck</varname> is <literal>true</literal>. |
||||
</para> |
||||
</listitem> |
||||
<listitem> |
||||
<para> |
||||
Apache HTTPD: |
||||
<link |
||||
xlink:href="https://github.com/NixOS/nixpkgs/blob/master/pkgs/servers/http/apache-httpd/2.4.nix"><filename>pkgs/servers/http/apache-httpd/2.4.nix</filename></link>. |
||||
A bunch of optional features, variable substitutions in the |
||||
configure flags, a post-install hook, and miscellaneous |
||||
hackery.</para> |
||||
</listitem> |
||||
|
||||
<listitem> |
||||
<para>Thunderbird: <link |
||||
A bunch of optional features, variable substitutions in the configure |
||||
flags, a post-install hook, and miscellaneous hackery. |
||||
</para> |
||||
</listitem> |
||||
<listitem> |
||||
<para> |
||||
Thunderbird: |
||||
<link |
||||
xlink:href="https://github.com/NixOS/nixpkgs/blob/master/pkgs/applications/networking/mailreaders/thunderbird/default.nix"><filename>pkgs/applications/networking/mailreaders/thunderbird/default.nix</filename></link>. |
||||
Lots of dependencies.</para> |
||||
</listitem> |
||||
|
||||
<listitem> |
||||
<para>JDiskReport, a Java utility: <link |
||||
Lots of dependencies. |
||||
</para> |
||||
</listitem> |
||||
<listitem> |
||||
<para> |
||||
JDiskReport, a Java utility: |
||||
<link |
||||
xlink:href="https://github.com/NixOS/nixpkgs/blob/master/pkgs/tools/misc/jdiskreport/default.nix"><filename>pkgs/tools/misc/jdiskreport/default.nix</filename></link> |
||||
(and the <link |
||||
(and the |
||||
<link |
||||
xlink:href="https://github.com/NixOS/nixpkgs/blob/master/pkgs/tools/misc/jdiskreport/builder.sh">builder</link>). |
||||
Nixpkgs doesn’t have a decent <varname>stdenv</varname> for |
||||
Java yet so this is pretty ad-hoc.</para> |
||||
</listitem> |
||||
|
||||
<listitem> |
||||
<para>XML::Simple, a Perl module: <link |
||||
Nixpkgs doesn’t have a decent <varname>stdenv</varname> for Java yet |
||||
so this is pretty ad-hoc. |
||||
</para> |
||||
</listitem> |
||||
<listitem> |
||||
<para> |
||||
XML::Simple, a Perl module: |
||||
<link |
||||
xlink:href="https://github.com/NixOS/nixpkgs/blob/master/pkgs/top-level/perl-packages.nix"><filename>pkgs/top-level/perl-packages.nix</filename></link> |
||||
(search for the <varname>XMLSimple</varname> attribute). |
||||
Most Perl modules are so simple to build that they are |
||||
defined directly in <filename>perl-packages.nix</filename>; |
||||
no need to make a separate file for them.</para> |
||||
</listitem> |
||||
|
||||
<listitem> |
||||
<para>Adobe Reader: <link |
||||
(search for the <varname>XMLSimple</varname> attribute). Most Perl |
||||
modules are so simple to build that they are defined directly in |
||||
<filename>perl-packages.nix</filename>; no need to make a separate file |
||||
for them. |
||||
</para> |
||||
</listitem> |
||||
<listitem> |
||||
<para> |
||||
Adobe Reader: |
||||
<link |
||||
xlink:href="https://github.com/NixOS/nixpkgs/blob/master/pkgs/applications/misc/adobe-reader/default.nix"><filename>pkgs/applications/misc/adobe-reader/default.nix</filename></link>. |
||||
Shows how binary-only packages can be supported. In |
||||
particular the <link |
||||
Shows how binary-only packages can be supported. In particular the |
||||
<link |
||||
xlink:href="https://github.com/NixOS/nixpkgs/blob/master/pkgs/applications/misc/adobe-reader/builder.sh">builder</link> |
||||
uses <command>patchelf</command> to set the RUNPATH and ELF |
||||
interpreter of the executables so that the right libraries |
||||
are found at runtime.</para> |
||||
</listitem> |
||||
|
||||
</itemizedlist> |
||||
|
||||
uses <command>patchelf</command> to set the RUNPATH and ELF interpreter |
||||
of the executables so that the right libraries are found at runtime. |
||||
</para> |
||||
</listitem> |
||||
</itemizedlist> |
||||
</para> |
||||
|
||||
<para>Some notes: |
||||
|
||||
<itemizedlist> |
||||
|
||||
<listitem> |
||||
<para>All <varname linkend="chap-meta">meta</varname> |
||||
attributes are optional, but it’s still a good idea to |
||||
provide at least the <varname>description</varname>, |
||||
<varname>homepage</varname> and <varname |
||||
linkend="sec-meta-license">license</varname>.</para> |
||||
</listitem> |
||||
|
||||
<listitem> |
||||
<para>You can use <command>nix-prefetch-url</command> (or similar nix-prefetch-git, etc) |
||||
<replaceable>url</replaceable> to get the SHA-256 hash of |
||||
source distributions. There are similar commands as <command>nix-prefetch-git</command> and |
||||
<command>nix-prefetch-hg</command> available in <literal>nix-prefetch-scripts</literal> package.</para> |
||||
</listitem> |
||||
|
||||
<listitem> |
||||
<para>A list of schemes for <literal>mirror://</literal> |
||||
URLs can be found in <link |
||||
xlink:href="https://github.com/NixOS/nixpkgs/blob/master/pkgs/build-support/fetchurl/mirrors.nix"><filename>pkgs/build-support/fetchurl/mirrors.nix</filename></link>.</para> |
||||
</listitem> |
||||
|
||||
</itemizedlist> |
||||
|
||||
<para> |
||||
Some notes: |
||||
<itemizedlist> |
||||
<listitem> |
||||
<para> |
||||
All <varname linkend="chap-meta">meta</varname> attributes are |
||||
optional, but it’s still a good idea to provide at least the |
||||
<varname>description</varname>, <varname>homepage</varname> and |
||||
<varname |
||||
linkend="sec-meta-license">license</varname>. |
||||
</para> |
||||
</listitem> |
||||
<listitem> |
||||
<para> |
||||
You can use <command>nix-prefetch-url</command> (or similar |
||||
nix-prefetch-git, etc) <replaceable>url</replaceable> to get the |
||||
SHA-256 hash of source distributions. There are similar commands as |
||||
<command>nix-prefetch-git</command> and |
||||
<command>nix-prefetch-hg</command> available in |
||||
<literal>nix-prefetch-scripts</literal> package. |
||||
</para> |
||||
</listitem> |
||||
<listitem> |
||||
<para> |
||||
A list of schemes for <literal>mirror://</literal> URLs can be found in |
||||
<link |
||||
xlink:href="https://github.com/NixOS/nixpkgs/blob/master/pkgs/build-support/fetchurl/mirrors.nix"><filename>pkgs/build-support/fetchurl/mirrors.nix</filename></link>. |
||||
</para> |
||||
</listitem> |
||||
</itemizedlist> |
||||
</para> |
||||
|
||||
<para>The exact syntax and semantics of the Nix expression |
||||
language, including the built-in function, are described in the |
||||
Nix manual in the <link |
||||
<para> |
||||
The exact syntax and semantics of the Nix expression language, including |
||||
the built-in function, are described in the Nix manual in the |
||||
<link |
||||
xlink:href="http://hydra.nixos.org/job/nix/trunk/tarball/latest/download-by-type/doc/manual/#chap-writing-nix-expressions">chapter |
||||
on writing Nix expressions</link>.</para> |
||||
|
||||
</listitem> |
||||
|
||||
<listitem> |
||||
<para>Add a call to the function defined in the previous step to |
||||
<link |
||||
on writing Nix expressions</link>. |
||||
</para> |
||||
</listitem> |
||||
<listitem> |
||||
<para> |
||||
Add a call to the function defined in the previous step to |
||||
<link |
||||
xlink:href="https://github.com/NixOS/nixpkgs/blob/master/pkgs/top-level/all-packages.nix"><filename>pkgs/top-level/all-packages.nix</filename></link> |
||||
with some descriptive name for the variable, |
||||
e.g. <varname>libfoo</varname>. |
||||
|
||||
<screen> |
||||
with some descriptive name for the variable, e.g. |
||||
<varname>libfoo</varname>. |
||||
<screen> |
||||
$ emacs pkgs/top-level/all-packages.nix</screen> |
||||
|
||||
</para> |
||||
|
||||
<para>The attributes in that file are sorted by category (like |
||||
“Development / Libraries”) that more-or-less correspond to the |
||||
directory structure of Nixpkgs, and then by attribute name.</para> |
||||
</listitem> |
||||
|
||||
<listitem> |
||||
<para>To test whether the package builds, run the following command |
||||
from the root of the nixpkgs source tree: |
||||
|
||||
<screen> |
||||
<para> |
||||
The attributes in that file are sorted by category (like “Development / |
||||
Libraries”) that more-or-less correspond to the directory structure of |
||||
Nixpkgs, and then by attribute name. |
||||
</para> |
||||
</listitem> |
||||
<listitem> |
||||
<para> |
||||
To test whether the package builds, run the following command from the |
||||
root of the nixpkgs source tree: |
||||
<screen> |
||||
$ nix-build -A libfoo</screen> |
||||
|
||||
where <varname>libfoo</varname> should be the variable name |
||||
defined in the previous step. You may want to add the flag |
||||
<option>-K</option> to keep the temporary build directory in case |
||||
something fails. If the build succeeds, a symlink |
||||
<filename>./result</filename> to the package in the Nix store is |
||||
created.</para> |
||||
</listitem> |
||||
|
||||
<listitem> |
||||
<para>If you want to install the package into your profile |
||||
(optional), do |
||||
|
||||
<screen> |
||||
where <varname>libfoo</varname> should be the variable name defined in the |
||||
previous step. You may want to add the flag <option>-K</option> to keep |
||||
the temporary build directory in case something fails. If the build |
||||
succeeds, a symlink <filename>./result</filename> to the package in the |
||||
Nix store is created. |
||||
</para> |
||||
</listitem> |
||||
<listitem> |
||||
<para> |
||||
If you want to install the package into your profile (optional), do |
||||
<screen> |
||||
$ nix-env -f . -iA libfoo</screen> |
||||
|
||||
</para> |
||||
</listitem> |
||||
|
||||
<listitem> |
||||
<para>Optionally commit the new package and open a pull request, or send a patch to |
||||
<literal>https://groups.google.com/forum/#!forum/nix-devel</literal>.</para> |
||||
</listitem> |
||||
|
||||
|
||||
</orderedlist> |
||||
|
||||
</para> |
||||
|
||||
</listitem> |
||||
<listitem> |
||||
<para> |
||||
Optionally commit the new package and open a pull request, or send a patch |
||||
to <literal>https://groups.google.com/forum/#!forum/nix-devel</literal>. |
||||
</para> |
||||
</listitem> |
||||
</orderedlist> |
||||
</para> |
||||
</chapter> |
||||
|
File diff suppressed because it is too large
Load Diff
@ -0,0 +1,5 @@ |
||||
{ pkgs ? import ../. {} }: |
||||
(import ./default.nix).overrideAttrs (x: { |
||||
buildInputs = x.buildInputs ++ [ pkgs.xmloscopy ]; |
||||
|
||||
}) |
File diff suppressed because it is too large
Load Diff
@ -0,0 +1,10 @@ |
||||
{ lib, ... }: |
||||
|
||||
{ |
||||
options = { |
||||
value = lib.mkOption { |
||||
default = "12"; |
||||
type = lib.types.coercedTo lib.types.str lib.toInt lib.types.ints.s8; |
||||
}; |
||||
}; |
||||
} |
@ -0,0 +1,3 @@ |
||||
{ |
||||
value = "foobar"; |
||||
} |
@ -0,0 +1,3 @@ |
||||
{ |
||||
value = "1000"; |
||||
} |
@ -0,0 +1,19 @@ |
||||
{ config, lib, ... }: |
||||
|
||||
{ |
||||
options = { |
||||
loaOfInt = lib.mkOption { |
||||
type = lib.types.loaOf lib.types.int; |
||||
}; |
||||
|
||||
result = lib.mkOption { |
||||
type = lib.types.str; |
||||
}; |
||||
}; |
||||
|
||||
config = { |
||||
loaOfInt = [ 1 2 3 4 5 6 7 8 9 10 ]; |
||||
|
||||
result = toString (lib.attrValues config.loaOfInt); |
||||
}; |
||||
} |
@ -0,0 +1,19 @@ |
||||
{ config, lib, ... }: |
||||
|
||||
{ |
||||
options = { |
||||
loaOfInt = lib.mkOption { |
||||
type = lib.types.loaOf lib.types.int; |
||||
}; |
||||
|
||||
result = lib.mkOption { |
||||
type = lib.types.str; |
||||
}; |
||||
}; |
||||
|
||||
config = { |
||||
loaOfInt = lib.mkMerge (map lib.singleton [ 1 2 3 4 5 6 7 8 9 10 ]); |
||||
|
||||
result = toString (lib.attrValues config.loaOfInt); |
||||
}; |
||||
} |
@ -0,0 +1,2 @@ |
||||
generated |
||||
manual-combined.xml |
@ -0,0 +1,24 @@ |
||||
.PHONY: all |
||||
all: manual-combined.xml format |
||||
|
||||
.PHONY: debug |
||||
debug: generated manual-combined.xml |
||||
|
||||
manual-combined.xml: generated *.xml |
||||
rm -f ./manual-combined.xml
|
||||
nix-shell --packages xmloscopy \
|
||||
--run "xmloscopy --docbook5 ./manual.xml ./manual-combined.xml"
|
||||
|
||||
.PHONY: format |
||||
format: |
||||
find . -iname '*.xml' -type f -print0 | xargs -0 -I{} -n1 \
|
||||
xmlformat --config-file "../xmlformat.conf" -i {}
|
||||
|
||||
.PHONY: clean |
||||
clean: |
||||
rm -f manual-combined.xml generated
|
||||
|
||||
generated: ./options-to-docbook.xsl |
||||
nix-build ../../release.nix \
|
||||
--attr manualGeneratedSources.x86_64-linux \
|
||||
--out-link ./generated
|
Some files were not shown because too many files have changed in this diff Show More
Loading…
Reference in new issue