diff options
Diffstat (limited to 'doc/languages-frameworks/bower.xml')
| -rw-r--r-- | doc/languages-frameworks/bower.xml | 289 |
1 files changed, 137 insertions, 152 deletions
diff --git a/doc/languages-frameworks/bower.xml b/doc/languages-frameworks/bower.xml index 742d3c2e9fe5..db7536cdc14e 100644 --- a/doc/languages-frameworks/bower.xml +++ b/doc/languages-frameworks/bower.xml @@ -1,40 +1,37 @@ <section xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xml:id="sec-bower"> - -<title>Bower</title> - -<para> - <link xlink:href="http://bower.io">Bower</link> is a package manager - for web site front-end components. Bower packages (comprising of - build artefacts and sometimes sources) are stored in - <command>git</command> repositories, typically on Github. The - package registry is run by the Bower team with package metadata - coming from the <filename>bower.json</filename> file within each - package. -</para> - -<para> - The end result of running Bower is a - <filename>bower_components</filename> directory which can be included - in the web app's build process. -</para> - -<para> + <title>Bower</title> + + <para> + <link xlink:href="http://bower.io">Bower</link> is a package manager for web + site front-end components. Bower packages (comprising of build artefacts and + sometimes sources) are stored in <command>git</command> repositories, + typically on Github. The package registry is run by the Bower team with + package metadata coming from the <filename>bower.json</filename> file within + each package. + </para> + + <para> + The end result of running Bower is a <filename>bower_components</filename> + directory which can be included in the web app's build process. + </para> + + <para> Bower can be run interactively, by installing <varname>nodePackages.bower</varname>. More interestingly, the Bower components can be declared in a Nix derivation, with the help of <varname>nodePackages.bower2nix</varname>. -</para> + </para> -<section xml:id="ssec-bower2nix-usage"> + <section xml:id="ssec-bower2nix-usage"> <title><command>bower2nix</command> usage</title> -<para> - Suppose you have a <filename>bower.json</filename> with the following contents: - - -<example xml:id="ex-bowerJson"><title><filename>bower.json</filename></title> + <para> + Suppose you have a <filename>bower.json</filename> with the following + contents: + <example xml:id="ex-bowerJson"> + <title><filename>bower.json</filename></title> <programlisting language="json"> <![CDATA[{ "name": "my-web-app", @@ -44,14 +41,12 @@ } }]]> </programlisting> -</example> -</para> - - -<para> - Running <command>bower2nix</command> will produce something like the - following output: + </example> + </para> + <para> + Running <command>bower2nix</command> will produce something like the + following output: <programlisting language="nix"> <![CDATA[{ fetchbower, buildEnv }: buildEnv { name = "bower-env"; ignoreCollisions = true; paths = [ @@ -60,31 +55,31 @@ buildEnv { name = "bower-env"; ignoreCollisions = true; paths = [ (fetchbower "jquery" "2.2.2" "1.9.1 - 2" "10sp5h98sqwk90y4k6hbdviwqzvzwqf47r3r51pakch5ii2y7js1") ]; }]]> </programlisting> -</para> - + </para> -<para> - Using the <command>bower2nix</command> command line arguments, the - output can be redirected to a file. A name like - <filename>bower-packages.nix</filename> would be fine. -</para> + <para> + Using the <command>bower2nix</command> command line arguments, the output + can be redirected to a file. A name like + <filename>bower-packages.nix</filename> would be fine. + </para> -<para> - 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 - <varname>buildBowerComponents</varname> is useful. -</para> -</section> + <para> + 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 <varname>buildBowerComponents</varname> is useful. + </para> + </section> -<section xml:id="ssec-build-bower-components"><title><varname>buildBowerComponents</varname> function</title> + <section xml:id="ssec-build-bower-components"> + <title><varname>buildBowerComponents</varname> function</title> <para> - The function is implemented in <link xlink:href="https://github.com/NixOS/nixpkgs/blob/master/pkgs/development/bower-modules/generic/default.nix"> - <filename>pkgs/development/bower-modules/generic/default.nix</filename></link>. - Example usage: - -<example xml:id="ex-buildBowerComponents"><title>buildBowerComponents</title> + The function is implemented in + <link xlink:href="https://github.com/NixOS/nixpkgs/blob/master/pkgs/development/bower-modules/generic/default.nix"> + <filename>pkgs/development/bower-modules/generic/default.nix</filename></link>. + Example usage: + <example xml:id="ex-buildBowerComponents"> + <title>buildBowerComponents</title> <programlisting language="nix"> bowerComponents = buildBowerComponents { name = "my-web-app"; @@ -92,42 +87,42 @@ bowerComponents = buildBowerComponents { src = myWebApp; <co xml:id="ex-buildBowerComponents-2" /> }; </programlisting> -</example> + </example> </para> -<para> -In <xref linkend="ex-buildBowerComponents" />, the following arguments -are of special significance to the function: - -<calloutlist> - <callout arearefs="ex-buildBowerComponents-1"> - <para> - <varname>generated</varname> specifies the file which was created by <command>bower2nix</command>. - </para> - </callout> - - <callout arearefs="ex-buildBowerComponents-2"> - <para> - <varname>src</varname> is your project's sources. It needs to - contain a <filename>bower.json</filename> file. - </para> - </callout> -</calloutlist> -</para> - -<para> - <varname>buildBowerComponents</varname> will run Bower to link - together the output of <command>bower2nix</command>, resulting in a - <filename>bower_components</filename> directory which can be used. -</para> - -<para> - Here is an example of a web frontend build process using - <command>gulp</command>. You might use <command>grunt</command>, or - anything else. -</para> - -<example xml:id="ex-bowerGulpFile"><title>Example build script (<filename>gulpfile.js</filename>)</title> + <para> + In <xref linkend="ex-buildBowerComponents" />, the following arguments are + of special significance to the function: + <calloutlist> + <callout arearefs="ex-buildBowerComponents-1"> + <para> + <varname>generated</varname> specifies the file which was created by + <command>bower2nix</command>. + </para> + </callout> + <callout arearefs="ex-buildBowerComponents-2"> + <para> + <varname>src</varname> is your project's sources. It needs to contain a + <filename>bower.json</filename> file. + </para> + </callout> + </calloutlist> + </para> + + <para> + <varname>buildBowerComponents</varname> will run Bower to link together the + output of <command>bower2nix</command>, resulting in a + <filename>bower_components</filename> directory which can be used. + </para> + + <para> + Here is an example of a web frontend build process using + <command>gulp</command>. You might use <command>grunt</command>, or anything + else. + </para> + + <example xml:id="ex-bowerGulpFile"> + <title>Example build script (<filename>gulpfile.js</filename>)</title> <programlisting language="javascript"> <![CDATA[var gulp = require('gulp'); @@ -142,10 +137,10 @@ gulp.task('build', [], function () { .pipe(gulp.dest("./gulpdist/")); });]]> </programlisting> -</example> + </example> -<example xml:id="ex-buildBowerComponentsDefaultNix"> - <title>Full example — <filename>default.nix</filename></title> + <example xml:id="ex-buildBowerComponentsDefaultNix"> + <title>Full example — <filename>default.nix</filename></title> <programlisting language="nix"> { myWebApp ? { outPath = ./.; name = "myWebApp"; } , pkgs ? import <nixpkgs> {} @@ -172,73 +167,63 @@ pkgs.stdenv.mkDerivation { installPhase = "mv gulpdist $out"; } </programlisting> -</example> - -<para> -A few notes about <xref linkend="ex-buildBowerComponentsDefaultNix" />: - -<calloutlist> - <callout arearefs="ex-buildBowerComponentsDefault-1"> - <para> - The result of <varname>buildBowerComponents</varname> is an - input to the frontend build. - </para> - </callout> - - <callout arearefs="ex-buildBowerComponentsDefault-2"> - <para> - Whether to symlink or copy the - <filename>bower_components</filename> directory depends on the - build tool in use. In this case a copy is used to avoid - <command>gulp</command> silliness with permissions. - </para> - </callout> - - <callout arearefs="ex-buildBowerComponentsDefault-3"> - <para> - <command>gulp</command> requires <varname>HOME</varname> to - refer to a writeable directory. - </para> - </callout> - - <callout arearefs="ex-buildBowerComponentsDefault-4"> - <para> + </example> + + <para> + A few notes about <xref linkend="ex-buildBowerComponentsDefaultNix" />: + <calloutlist> + <callout arearefs="ex-buildBowerComponentsDefault-1"> + <para> + The result of <varname>buildBowerComponents</varname> is an input to the + frontend build. + </para> + </callout> + <callout arearefs="ex-buildBowerComponentsDefault-2"> + <para> + Whether to symlink or copy the <filename>bower_components</filename> + directory depends on the build tool in use. In this case a copy is used + to avoid <command>gulp</command> silliness with permissions. + </para> + </callout> + <callout arearefs="ex-buildBowerComponentsDefault-3"> + <para> + <command>gulp</command> requires <varname>HOME</varname> to refer to a + writeable directory. + </para> + </callout> + <callout arearefs="ex-buildBowerComponentsDefault-4"> + <para> The actual build command. Other tools could be used. - </para> - </callout> -</calloutlist> -</para> -</section> + </para> + </callout> + </calloutlist> + </para> + </section> -<section xml:id="ssec-bower2nix-troubleshooting"> + <section xml:id="ssec-bower2nix-troubleshooting"> <title>Troubleshooting</title> -<variablelist> - - <varlistentry> - <term> - <literal>ENOCACHE</literal> errors from + <variablelist> + <varlistentry> + <term><literal>ENOCACHE</literal> errors from <varname>buildBowerComponents</varname> </term> <listitem> - <para> - This means that Bower was looking for a package version which - doesn't exist in the generated - <filename>bower-packages.nix</filename>. - </para> - <para> - If <filename>bower.json</filename> has been updated, then run - <command>bower2nix</command> again. - </para> - <para> - It could also be a bug in <command>bower2nix</command> or - <command>fetchbower</command>. If possible, try reformulating - the version specification in <filename>bower.json</filename>. - </para> + <para> + This means that Bower was looking for a package version which doesn't + exist in the generated <filename>bower-packages.nix</filename>. + </para> + <para> + If <filename>bower.json</filename> has been updated, then run + <command>bower2nix</command> again. + </para> + <para> + It could also be a bug in <command>bower2nix</command> or + <command>fetchbower</command>. If possible, try reformulating the version + specification in <filename>bower.json</filename>. + </para> </listitem> - </varlistentry> -</variablelist> - -</section> - + </varlistentry> + </variablelist> + </section> </section> |