From 123da5c1c181e3a7b8136d932ec7d27fa7435ece Mon Sep 17 00:00:00 2001 From: Rodney Lorrimar Date: Sat, 26 Mar 2016 16:50:45 +0000 Subject: nixpkgs manual: Add documentation for bower2nix Fixes #9459 Fixes #13214 --- doc/languages-frameworks/bower.xml | 244 +++++++++++++++++++++++++++++++++++++ doc/languages-frameworks/index.xml | 18 +++ 2 files changed, 262 insertions(+) create mode 100644 doc/languages-frameworks/bower.xml (limited to 'doc') diff --git a/doc/languages-frameworks/bower.xml b/doc/languages-frameworks/bower.xml new file mode 100644 index 000000000000..742d3c2e9fe5 --- /dev/null +++ b/doc/languages-frameworks/bower.xml @@ -0,0 +1,244 @@ +
+ +Bower + + + Bower is a package manager + for web site front-end components. Bower packages (comprising of + build artefacts and sometimes sources) are stored in + git repositories, typically on Github. The + package registry is run by the Bower team with package metadata + coming from the bower.json file within each + package. + + + + The end result of running Bower is a + bower_components directory which can be included + in the web app's build process. + + + + Bower can be run interactively, by installing + nodePackages.bower. More interestingly, the Bower + components can be declared in a Nix derivation, with the help of + nodePackages.bower2nix. + + +
+ <command>bower2nix</command> usage + + + Suppose you have a bower.json with the following contents: + + +<filename>bower.json</filename> + + + + + + + + + Running bower2nix will produce something like the + following output: + + + + + + + + + Using the bower2nix command line arguments, the + output can be redirected to a file. A name like + bower-packages.nix would be fine. + + + + The resulting derivation is a union of all the downloaded Bower + packages (and their dependencies). To use it, they still need to be + linked together by Bower, which is where + buildBowerComponents is useful. + +
+ +
<varname>buildBowerComponents</varname> function + + + The function is implemented in + pkgs/development/bower-modules/generic/default.nix. + Example usage: + +buildBowerComponents + +bowerComponents = buildBowerComponents { + name = "my-web-app"; + generated = ./bower-packages.nix; + src = myWebApp; +}; + + + + + +In , the following arguments +are of special significance to the function: + + + + + generated specifies the file which was created by bower2nix. + + + + + + src is your project's sources. It needs to + contain a bower.json file. + + + + + + + buildBowerComponents will run Bower to link + together the output of bower2nix, resulting in a + bower_components directory which can be used. + + + + Here is an example of a web frontend build process using + gulp. You might use grunt, or + anything else. + + +Example build script (<filename>gulpfile.js</filename>) + + + + + + + Full example — <filename>default.nix</filename> + +{ myWebApp ? { outPath = ./.; name = "myWebApp"; } +, pkgs ? import <nixpkgs> {} +}: + +pkgs.stdenv.mkDerivation { + name = "my-web-app-frontend"; + src = myWebApp; + + buildInputs = [ pkgs.nodePackages.gulp ]; + + bowerComponents = pkgs.buildBowerComponents { + name = "my-web-app"; + generated = ./bower-packages.nix; + src = myWebApp; + }; + + buildPhase = '' + cp --reflink=auto --no-preserve=mode -R $bowerComponents/bower_components . + export HOME=$PWD + ${pkgs.nodePackages.gulp}/bin/gulp build + ''; + + installPhase = "mv gulpdist $out"; +} + + + + +A few notes about : + + + + + The result of buildBowerComponents is an + input to the frontend build. + + + + + + Whether to symlink or copy the + bower_components directory depends on the + build tool in use. In this case a copy is used to avoid + gulp silliness with permissions. + + + + + + gulp requires HOME to + refer to a writeable directory. + + + + + + The actual build command. Other tools could be used. + + + + +
+ +
+ Troubleshooting + + + + + + ENOCACHE errors from + buildBowerComponents + + + + This means that Bower was looking for a package version which + doesn't exist in the generated + bower-packages.nix. + + + If bower.json has been updated, then run + bower2nix again. + + + It could also be a bug in bower2nix or + fetchbower. If possible, try reformulating + the version specification in bower.json. + + + + + +
+ +
diff --git a/doc/languages-frameworks/index.xml b/doc/languages-frameworks/index.xml index ab62afa40d61..63c4b7dec607 100644 --- a/doc/languages-frameworks/index.xml +++ b/doc/languages-frameworks/index.xml @@ -24,6 +24,24 @@ such as Perl or Haskell. These are described in this chapter. + + + + +>>>>>>> 05113a5... nixpkgs manual: Add documentation for bower2nix -- cgit 1.4.1