forked from mirrors/nixpkgs
Merge pull request #37749 from grahamc/nixpkgs-docs
Make Nixpkgs docs less frustrating to hack on
This commit is contained in:
Graham Christensen
GitHub
commit
37f50c15da
5
doc/.gitignore
vendored
Normal file
5
doc/.gitignore
vendored
Normal file
|
|
@ -0,0 +1,5 @@
|
||||||
|
*.chapter.xml
|
||||||
|
*.section.xml
|
||||||
|
.version
|
||||||
|
out
|
||||||
|
manual-full.xml
|
||||||
74
doc/Makefile
Normal file
74
doc/Makefile
Normal file
|
|
@ -0,0 +1,74 @@
|
||||||
|
MD_TARGETS=$(addsuffix .xml, $(basename $(wildcard ./*.md ./**/*.md)))
|
||||||
|
|
||||||
|
.PHONY: all
|
||||||
|
all: validate out/html/index.html out/epub/manual.epub
|
||||||
|
|
||||||
|
.PHONY: debug
|
||||||
|
debug:
|
||||||
|
nix-shell --run "xmloscopy --docbook5 ./manual.xml ./manual-full.xml"
|
||||||
|
.PHONY: clean
|
||||||
|
clean:
|
||||||
|
rm -f ${MD_TARGETS} .version manual-full.xml
|
||||||
|
rm -rf ./out/
|
||||||
|
|
||||||
|
.PHONY: validate
|
||||||
|
validate: manual-full.xml
|
||||||
|
jing "$$RNG" manual-full.xml
|
||||||
|
|
||||||
|
out/html/index.html: manual-full.xml style.css
|
||||||
|
mkdir -p out/html
|
||||||
|
xsltproc $$xsltFlags \
|
||||||
|
--nonet --xinclude \
|
||||||
|
--output $@ \
|
||||||
|
"$$XSL/docbook/xhtml/docbook.xsl" \
|
||||||
|
./manual-full.xml
|
||||||
|
|
||||||
|
cp ./style.css out/html/style.css
|
||||||
|
|
||||||
|
mkdir -p out/html/images/callouts
|
||||||
|
cp "$$XSL/docbook/images/callouts/"*.gif out/html/images/callouts/
|
||||||
|
chmod u+w -R out/html/images/
|
||||||
|
|
||||||
|
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 "$$XSL/docbook/images/callouts/"*.gif out/epub/scratch/OEBPS
|
||||||
|
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/"
|
||||||
|
|
||||||
|
manual-full.xml: ${MD_TARGETS} .version *.xml
|
||||||
|
xmllint --nonet --xinclude --noxincludenode manual.xml --output manual-full.xml
|
||||||
|
|
||||||
|
.version:
|
||||||
|
nix-instantiate --eval \
|
||||||
|
-E '(import ../lib).nixpkgsVersion' > .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 > $@
|
||||||
|
|
@ -6,12 +6,27 @@
|
||||||
|
|
||||||
<para>The DocBook sources of the Nixpkgs manual are in the <filename
|
<para>The DocBook sources of the Nixpkgs manual are in the <filename
|
||||||
xlink:href="https://github.com/NixOS/nixpkgs/tree/master/doc">doc</filename>
|
xlink:href="https://github.com/NixOS/nixpkgs/tree/master/doc">doc</filename>
|
||||||
subdirectory of the Nixpkgs repository. If you make modifications to
|
subdirectory of the Nixpkgs repository.</para>
|
||||||
the manual, it's important to build it before committing. You can do that as follows:
|
|
||||||
|
<para>You can quickly check your edits with <command>make</command>:</para>
|
||||||
|
|
||||||
<screen>
|
<screen>
|
||||||
$ cd /path/to/nixpkgs
|
$ cd /path/to/nixpkgs/doc
|
||||||
$ nix-build doc
|
$ nix-shell
|
||||||
|
[nix-shell]$ make
|
||||||
|
</screen>
|
||||||
|
|
||||||
|
<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>
|
</screen>
|
||||||
|
|
||||||
If the build succeeds, the manual will be in
|
If the build succeeds, the manual will be in
|
||||||
|
|
|
||||||
129
doc/default.nix
129
doc/default.nix
|
|
@ -7,116 +7,35 @@ in
|
||||||
pkgs.stdenv.mkDerivation {
|
pkgs.stdenv.mkDerivation {
|
||||||
name = "nixpkgs-manual";
|
name = "nixpkgs-manual";
|
||||||
|
|
||||||
|
buildInputs = with pkgs; [ pandoc libxml2 libxslt zip jing ];
|
||||||
|
|
||||||
buildInputs = with pkgs; [ pandoc libxml2 libxslt zip ];
|
src = ./.;
|
||||||
|
|
||||||
xsltFlags = ''
|
XSL = "${pkgs.docbook5_xsl}/xml/xsl";
|
||||||
--param section.autolabel 1
|
RNG = "${pkgs.docbook5}/xml/rng/docbook/docbook.rng";
|
||||||
--param section.label.includes.component.label 1
|
xsltFlags = lib.concatStringsSep " " [
|
||||||
--param html.stylesheet 'style.css'
|
"--param section.autolabel 1"
|
||||||
--param xref.with.number.and.title 1
|
"--param section.label.includes.component.label 1"
|
||||||
--param toc.section.depth 3
|
"--param html.stylesheet 'style.css'"
|
||||||
--param admon.style '''
|
"--param xref.with.number.and.title 1"
|
||||||
--param callout.graphics.extension '.gif'
|
"--param toc.section.depth 3"
|
||||||
|
"--param admon.style ''"
|
||||||
|
"--param callout.graphics.extension '.gif'"
|
||||||
|
];
|
||||||
|
|
||||||
|
postPatch = ''
|
||||||
|
echo ${lib.nixpkgsVersion} > .version
|
||||||
'';
|
'';
|
||||||
|
|
||||||
|
installPhase = ''
|
||||||
|
dest="$out/share/doc/nixpkgs"
|
||||||
|
mkdir -p "$(dirname "$dest")"
|
||||||
|
mv out/html "$dest"
|
||||||
|
mv "$dest/index.html" "$dest/manual.html"
|
||||||
|
|
||||||
buildCommand = let toDocbook = { useChapters ? false, inputFile, outputFile }:
|
mv out/epub/manual.epub "$dest/nixpkgs-manual.epub"
|
||||||
let
|
|
||||||
extraHeader = lib.optionalString (!useChapters)
|
|
||||||
''xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" '';
|
|
||||||
in ''
|
|
||||||
{
|
|
||||||
pandoc '${inputFile}' -w docbook+smart ${lib.optionalString useChapters "--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${extraHeader}|'
|
|
||||||
} > '${outputFile}'
|
|
||||||
'';
|
|
||||||
in
|
|
||||||
|
|
||||||
''
|
mkdir -p $out/nix-support/
|
||||||
ln -s '${sources}/'*.xml .
|
echo "doc manual $dest manual.html" >> $out/nix-support/hydra-build-products
|
||||||
mkdir ./languages-frameworks
|
|
||||||
cp -s '${sources-langs}'/* ./languages-frameworks
|
|
||||||
''
|
|
||||||
+ toDocbook {
|
|
||||||
inputFile = ./introduction.md;
|
|
||||||
outputFile = "introduction.xml";
|
|
||||||
useChapters = true;
|
|
||||||
}
|
|
||||||
+ toDocbook {
|
|
||||||
inputFile = ./shell.md;
|
|
||||||
outputFile = "shell.xml";
|
|
||||||
}
|
|
||||||
+ toDocbook {
|
|
||||||
inputFile = ./languages-frameworks/python.md;
|
|
||||||
outputFile = "./languages-frameworks/python.xml";
|
|
||||||
}
|
|
||||||
+ toDocbook {
|
|
||||||
inputFile = ./languages-frameworks/haskell.md;
|
|
||||||
outputFile = "./languages-frameworks/haskell.xml";
|
|
||||||
}
|
|
||||||
+ toDocbook {
|
|
||||||
inputFile = ../pkgs/development/idris-modules/README.md;
|
|
||||||
outputFile = "languages-frameworks/idris.xml";
|
|
||||||
}
|
|
||||||
+ toDocbook {
|
|
||||||
inputFile = ../pkgs/development/node-packages/README.md;
|
|
||||||
outputFile = "languages-frameworks/node.xml";
|
|
||||||
}
|
|
||||||
+ toDocbook {
|
|
||||||
inputFile = ../pkgs/development/r-modules/README.md;
|
|
||||||
outputFile = "languages-frameworks/r.xml";
|
|
||||||
}
|
|
||||||
+ toDocbook {
|
|
||||||
inputFile = ./languages-frameworks/rust.md;
|
|
||||||
outputFile = "./languages-frameworks/rust.xml";
|
|
||||||
}
|
|
||||||
+ toDocbook {
|
|
||||||
inputFile = ./languages-frameworks/vim.md;
|
|
||||||
outputFile = "./languages-frameworks/vim.xml";
|
|
||||||
}
|
|
||||||
+ toDocbook {
|
|
||||||
inputFile = ./languages-frameworks/emscripten.md;
|
|
||||||
outputFile = "./languages-frameworks/emscripten.xml";
|
|
||||||
}
|
|
||||||
+ ''
|
|
||||||
echo ${lib.nixpkgsVersion} > .version
|
|
||||||
|
|
||||||
# validate against relaxng schema
|
|
||||||
xmllint --nonet --xinclude --noxincludenode manual.xml --output manual-full.xml
|
|
||||||
${pkgs.jing}/bin/jing ${pkgs.docbook5}/xml/rng/docbook/docbook.rng manual-full.xml
|
|
||||||
|
|
||||||
dst=$out/share/doc/nixpkgs
|
|
||||||
mkdir -p $dst
|
|
||||||
xsltproc $xsltFlags --nonet --xinclude \
|
|
||||||
--output $dst/manual.html \
|
|
||||||
${pkgs.docbook5_xsl}/xml/xsl/docbook/xhtml/docbook.xsl \
|
|
||||||
./manual.xml
|
|
||||||
|
|
||||||
cp ${./style.css} $dst/style.css
|
|
||||||
|
|
||||||
mkdir -p $dst/images/callouts
|
|
||||||
cp "${pkgs.docbook5_xsl}/xml/xsl/docbook/images/callouts/"*.gif $dst/images/callouts/
|
|
||||||
|
|
||||||
mkdir -p $out/nix-support
|
|
||||||
echo "doc manual $dst manual.html" >> $out/nix-support/hydra-build-products
|
|
||||||
|
|
||||||
xsltproc $xsltFlags --nonet --xinclude \
|
|
||||||
--output $dst/epub/ \
|
|
||||||
${pkgs.docbook5_xsl}/xml/xsl/docbook/epub/docbook.xsl \
|
|
||||||
./manual.xml
|
|
||||||
|
|
||||||
cp -r $dst/images $dst/epub/OEBPS
|
|
||||||
echo "application/epub+zip" > mimetype
|
|
||||||
manual="$dst/nixpkgs-manual.epub"
|
|
||||||
zip -0Xq "$manual" mimetype
|
|
||||||
cd $dst/epub && zip -Xr9D "$manual" *
|
|
||||||
rm -rf $dst/epub
|
|
||||||
'';
|
'';
|
||||||
}
|
}
|
||||||
|
|
|
||||||
39
doc/languages-frameworks/idris.section.md
Normal file
39
doc/languages-frameworks/idris.section.md
Normal file
|
|
@ -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`.
|
||||||
|
|
@ -17,20 +17,20 @@ such as Perl or Haskell. These are described in this chapter.</para>
|
||||||
<xi:include href="bower.xml" />
|
<xi:include href="bower.xml" />
|
||||||
<xi:include href="coq.xml" />
|
<xi:include href="coq.xml" />
|
||||||
<xi:include href="go.xml" />
|
<xi:include href="go.xml" />
|
||||||
<xi:include href="haskell.xml" />
|
<xi:include href="haskell.section.xml" />
|
||||||
<xi:include href="idris.xml" /> <!-- generated from ../../pkgs/development/idris-modules/README.md -->
|
<xi:include href="idris.section.xml" />
|
||||||
<xi:include href="java.xml" />
|
<xi:include href="java.xml" />
|
||||||
<xi:include href="lua.xml" />
|
<xi:include href="lua.xml" />
|
||||||
<xi:include href="node.xml" /> <!-- generated from ../../pkgs/development/node-packages/README.md -->
|
<xi:include href="node.section.xml" />
|
||||||
<xi:include href="perl.xml" />
|
<xi:include href="perl.xml" />
|
||||||
<xi:include href="python.xml" />
|
<xi:include href="python.section.xml" />
|
||||||
<xi:include href="qt.xml" />
|
<xi:include href="qt.xml" />
|
||||||
<xi:include href="r.xml" /> <!-- generated from ../../pkgs/development/r-modules/README.md -->
|
<xi:include href="r.section.xml" />
|
||||||
<xi:include href="ruby.xml" />
|
<xi:include href="ruby.xml" />
|
||||||
<xi:include href="rust.xml" />
|
<xi:include href="rust.section.xml" />
|
||||||
<xi:include href="texlive.xml" />
|
<xi:include href="texlive.xml" />
|
||||||
<xi:include href="vim.xml" />
|
<xi:include href="vim.section.xml" />
|
||||||
<xi:include href="emscripten.xml" />
|
<xi:include href="emscripten.section.xml" />
|
||||||
|
|
||||||
|
|
||||||
</chapter>
|
</chapter>
|
||||||
|
|
|
||||||
51
doc/languages-frameworks/node.section.md
Normal file
51
doc/languages-frameworks/node.section.md
Normal file
|
|
@ -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.
|
||||||
120
doc/languages-frameworks/r.section.md
Normal file
120
doc/languages-frameworks/r.section.md
Normal file
|
|
@ -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`
|
||||||
|
|
@ -9,7 +9,7 @@
|
||||||
|
|
||||||
</info>
|
</info>
|
||||||
|
|
||||||
<xi:include href="introduction.xml" />
|
<xi:include href="introduction.chapter.xml" />
|
||||||
<xi:include href="quick-start.xml" />
|
<xi:include href="quick-start.xml" />
|
||||||
<xi:include href="stdenv.xml" />
|
<xi:include href="stdenv.xml" />
|
||||||
<xi:include href="multiple-output.xml" />
|
<xi:include href="multiple-output.xml" />
|
||||||
|
|
|
||||||
4
doc/shell.nix
Normal file
4
doc/shell.nix
Normal file
|
|
@ -0,0 +1,4 @@
|
||||||
|
{ pkgs ? import ../. {} }:
|
||||||
|
(import ./default.nix).overrideAttrs (x: {
|
||||||
|
buildInputs = x.buildInputs ++ [ pkgs.xmloscopy ];
|
||||||
|
})
|
||||||
|
|
@ -4,6 +4,8 @@ author: zimbatm
|
||||||
date: 2017-10-30
|
date: 2017-10-30
|
||||||
---
|
---
|
||||||
|
|
||||||
|
# mkShell
|
||||||
|
|
||||||
pkgs.mkShell is a special kind of derivation that is only useful when using
|
pkgs.mkShell is a special kind of derivation that is only useful when using
|
||||||
it combined with nix-shell. It will in fact fail to instantiate when invoked
|
it combined with nix-shell. It will in fact fail to instantiate when invoked
|
||||||
with nix-build.
|
with nix-build.
|
||||||
|
|
@ -1,39 +1 @@
|
||||||
Idris packages
|
Moved to [/doc/languages-frameworks/idris.section.md](/doc/languages-frameworks/idris.section.md)
|
||||||
==============
|
|
||||||
|
|
||||||
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,51 +1 @@
|
||||||
Node.js packages
|
Moved to [/doc/languages-frameworks/node.section.md](/doc/languages-frameworks/node.section.md)
|
||||||
================
|
|
||||||
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.
|
|
||||||
|
|
|
||||||
|
|
@ -1,120 +1 @@
|
||||||
R packages
|
Moved to [/doc/languages-frameworks/r.section.md](/doc/languages-frameworks/r.section.md)
|
||||||
==========
|
|
||||||
|
|
||||||
## 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`
|
|
||||||
|
|
|
||||||
Loading…
Reference in a new issue