diff options
Diffstat (limited to 'doc')
-rw-r--r-- | doc/default.nix | 40 | ||||
-rw-r--r-- | doc/introduction.chapter.md (renamed from doc/introduction.md) | 0 | ||||
-rw-r--r-- | doc/languages-frameworks/emscripten.section.md (renamed from doc/languages-frameworks/emscripten.md) | 0 | ||||
-rw-r--r-- | doc/languages-frameworks/haskell.section.md (renamed from doc/languages-frameworks/haskell.md) | 0 | ||||
-rw-r--r-- | doc/languages-frameworks/idris.section.md | 39 | ||||
-rw-r--r-- | doc/languages-frameworks/index.xml | 16 | ||||
-rw-r--r-- | doc/languages-frameworks/node.section.md | 51 | ||||
-rw-r--r-- | doc/languages-frameworks/python.section.md (renamed from doc/languages-frameworks/python.md) | 0 | ||||
-rw-r--r-- | doc/languages-frameworks/r.section.md | 120 | ||||
-rw-r--r-- | doc/languages-frameworks/rust.section.md (renamed from doc/languages-frameworks/rust.md) | 0 | ||||
-rw-r--r-- | doc/languages-frameworks/vim.section.md (renamed from doc/languages-frameworks/vim.md) | 0 | ||||
-rw-r--r-- | doc/manual.xml | 2 | ||||
-rw-r--r-- | doc/shell.section.md (renamed from doc/shell.md) | 0 |
13 files changed, 239 insertions, 29 deletions
diff --git a/doc/default.nix b/doc/default.nix index ec458634a42..1adcd796820 100644 --- a/doc/default.nix +++ b/doc/default.nix @@ -45,45 +45,45 @@ pkgs.stdenv.mkDerivation { cp -s '${sources-langs}'/* ./languages-frameworks '' + toDocbook { - inputFile = ./introduction.md; - outputFile = "introduction.xml"; + inputFile = ./introduction.chapter.md; + outputFile = "introduction.chapter.xml"; useChapters = true; } + toDocbook { - inputFile = ./shell.md; - outputFile = "shell.xml"; + inputFile = ./shell.section.md; + outputFile = "shell.section.xml"; } + toDocbook { - inputFile = ./languages-frameworks/python.md; - outputFile = "./languages-frameworks/python.xml"; + inputFile = ./languages-frameworks/python.section.md; + outputFile = "./languages-frameworks/python.section.xml"; } + toDocbook { - inputFile = ./languages-frameworks/haskell.md; - outputFile = "./languages-frameworks/haskell.xml"; + inputFile = ./languages-frameworks/haskell.section.md; + outputFile = "./languages-frameworks/haskell.section.xml"; } + toDocbook { - inputFile = ../pkgs/development/idris-modules/README.md; - outputFile = "languages-frameworks/idris.xml"; + inputFile = ./languages-frameworks/idris.section.md; + outputFile = "languages-frameworks/idris.section.xml"; } + toDocbook { - inputFile = ../pkgs/development/node-packages/README.md; - outputFile = "languages-frameworks/node.xml"; + inputFile = ./languages-frameworks/node.section.md; + outputFile = "languages-frameworks/node.section.xml"; } + toDocbook { - inputFile = ../pkgs/development/r-modules/README.md; - outputFile = "languages-frameworks/r.xml"; + inputFile = ./languages-frameworks/r.section.md; + outputFile = "languages-frameworks/r.section.xml"; } + toDocbook { - inputFile = ./languages-frameworks/rust.md; - outputFile = "./languages-frameworks/rust.xml"; + inputFile = ./languages-frameworks/rust.section.md; + outputFile = "./languages-frameworks/rust.section.xml"; } + toDocbook { - inputFile = ./languages-frameworks/vim.md; - outputFile = "./languages-frameworks/vim.xml"; + inputFile = ./languages-frameworks/vim.section.md; + outputFile = "./languages-frameworks/vim.section.xml"; } + toDocbook { - inputFile = ./languages-frameworks/emscripten.md; - outputFile = "./languages-frameworks/emscripten.xml"; + inputFile = ./languages-frameworks/emscripten.section.md; + outputFile = "./languages-frameworks/emscripten.section.xml"; } + '' echo ${lib.nixpkgsVersion} > .version diff --git a/doc/introduction.md b/doc/introduction.chapter.md index 8b03221c64b..8b03221c64b 100644 --- a/doc/introduction.md +++ b/doc/introduction.chapter.md diff --git a/doc/languages-frameworks/emscripten.md b/doc/languages-frameworks/emscripten.section.md index 24c49ec1409..24c49ec1409 100644 --- a/doc/languages-frameworks/emscripten.md +++ b/doc/languages-frameworks/emscripten.section.md diff --git a/doc/languages-frameworks/haskell.md b/doc/languages-frameworks/haskell.section.md index 1623e0d276f..1623e0d276f 100644 --- a/doc/languages-frameworks/haskell.md +++ b/doc/languages-frameworks/haskell.section.md diff --git a/doc/languages-frameworks/idris.section.md b/doc/languages-frameworks/idris.section.md new file mode 100644 index 00000000000..005ed360285 --- /dev/null +++ b/doc/languages-frameworks/idris.section.md @@ -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`. \ No newline at end of file diff --git a/doc/languages-frameworks/index.xml b/doc/languages-frameworks/index.xml index 6743c131201..a1c265f6748 100644 --- a/doc/languages-frameworks/index.xml +++ b/doc/languages-frameworks/index.xml @@ -17,20 +17,20 @@ such as Perl or Haskell. These are described in this chapter.</para> <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="haskell.section.xml" /> +<xi:include href="idris.section.xml" /> <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="node.section.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="r.xml" /> <!-- generated from ../../pkgs/development/r-modules/README.md --> +<xi:include href="r.section.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="vim.xml" /> -<xi:include href="emscripten.xml" /> +<xi:include href="vim.section.xml" /> +<xi:include href="emscripten.section.xml" /> </chapter> diff --git a/doc/languages-frameworks/node.section.md b/doc/languages-frameworks/node.section.md new file mode 100644 index 00000000000..17a203ed12b --- /dev/null +++ b/doc/languages-frameworks/node.section.md @@ -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. diff --git a/doc/languages-frameworks/python.md b/doc/languages-frameworks/python.section.md index 0f871395854..0f871395854 100644 --- a/doc/languages-frameworks/python.md +++ b/doc/languages-frameworks/python.section.md diff --git a/doc/languages-frameworks/r.section.md b/doc/languages-frameworks/r.section.md new file mode 100644 index 00000000000..c8f02bd1478 --- /dev/null +++ b/doc/languages-frameworks/r.section.md @@ -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` diff --git a/doc/languages-frameworks/rust.md b/doc/languages-frameworks/rust.section.md index f0498eac5b1..f0498eac5b1 100644 --- a/doc/languages-frameworks/rust.md +++ b/doc/languages-frameworks/rust.section.md diff --git a/doc/languages-frameworks/vim.md b/doc/languages-frameworks/vim.section.md index 1d6a4fe8da8..1d6a4fe8da8 100644 --- a/doc/languages-frameworks/vim.md +++ b/doc/languages-frameworks/vim.section.md diff --git a/doc/manual.xml b/doc/manual.xml index eb0a24789d4..385079eb578 100644 --- a/doc/manual.xml +++ b/doc/manual.xml @@ -9,7 +9,7 @@ </info> - <xi:include href="introduction.xml" /> + <xi:include href="introduction.chapter.xml" /> <xi:include href="quick-start.xml" /> <xi:include href="stdenv.xml" /> <xi:include href="multiple-output.xml" /> diff --git a/doc/shell.md b/doc/shell.section.md index 079574d4ae8..079574d4ae8 100644 --- a/doc/shell.md +++ b/doc/shell.section.md |