diff options
author | Wil Taylor <cert@wiltaylor.dev> | 2020-12-06 17:56:27 +1000 |
---|---|---|
committer | Jan Tojnar <jtojnar@gmail.com> | 2020-12-07 09:38:47 +0100 |
commit | 2eb20aa8ce7265c5348e1e234f65a09fc260ead3 (patch) | |
tree | 0f70c2f9cd44232a31ebe2f290ed437dc8a47752 /doc | |
parent | 6571462647d7316aff8b8597ecdf5922547bf365 (diff) |
doc: Converted Bower docs from xml to md
Diffstat (limited to 'doc')
-rw-r--r-- | doc/languages-frameworks/bower.section.md | 158 | ||||
-rw-r--r-- | doc/languages-frameworks/bower.xml | 196 | ||||
-rw-r--r-- | doc/languages-frameworks/index.xml | 2 |
3 files changed, 159 insertions, 197 deletions
diff --git a/doc/languages-frameworks/bower.section.md b/doc/languages-frameworks/bower.section.md new file mode 100644 index 000000000000..f408bd5b2c92 --- /dev/null +++ b/doc/languages-frameworks/bower.section.md @@ -0,0 +1,158 @@ +# Bower {#sec-bower} + +[Bower](https://bower.io) 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`. + +## bower2nix usage {#ssec-bower2nix-usage} + +Suppose you have a `bower.json` with the following contents: + +### Example bower.json {#ex-bowerJson} + +```json + "name": "my-web-app", + "dependencies": { + "angular": "~1.5.0", + "bootstrap": "~3.3.6" + } +``` + +Running `bower2nix` will produce something like the following output: + +```nix +{ fetchbower, buildEnv }: +buildEnv { name = "bower-env"; ignoreCollisions = true; paths = [ + (fetchbower "angular" "1.5.3" "~1.5.0" "1749xb0firxdra4rzadm4q9x90v6pzkbd7xmcyjk6qfza09ykk9y") + (fetchbower "bootstrap" "3.3.6" "~3.3.6" "1vvqlpbfcy0k5pncfjaiskj3y6scwifxygfqnw393sjfxiviwmbv") + (fetchbower "jquery" "2.2.2" "1.9.1 - 2" "10sp5h98sqwk90y4k6hbdviwqzvzwqf47r3r51pakch5ii2y7js1") +]; +``` + +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. + +## buildBowerComponents function {#ssec-build-bower-components} + +The function is implemented in [pkgs/development/bower-modules/generic/default.nix](https://github.com/NixOS/nixpkgs/blob/master/pkgs/development/bower-modules/generic/default.nix). + +### Example buildBowerComponents {#ex-buildBowerComponents} + +```{=docbook} +<programlisting language="nix"> +bowerComponents = buildBowerComponents { + name = "my-web-app"; + generated = ./bower-packages.nix; <co xml:id="ex-buildBowerComponents-1" /> + src = myWebApp; <co xml:id="ex-buildBowerComponents-2" /> +}; +</programlisting> +``` + +In ["buildBowerComponents" example](#ex-buildBowerComponents) the following arguments are of special significance to the function: + +```{=docbook} +<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> +``` + +`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 (gulpfile.js) {#ex-bowerGulpFile} + +```javascript +var gulp = require('gulp'); + +gulp.task('default', [], function () { + gulp.start('build'); +}); + +gulp.task('build', [], function () { + console.log("Just a dummy gulp build"); + gulp + .src(["./bower_components/**/*"]) + .pipe(gulp.dest("./gulpdist/")); +}); +``` + +### Example Full example — default.nix {#ex-buildBowerComponentsDefaultNix} + +```{=docbook} +<programlisting language="nix"> +{ myWebApp ? { outPath = ./.; name = "myWebApp"; } +, pkgs ? import <nixpkgs> {} +}: + +pkgs.stdenv.mkDerivation { + name = "my-web-app-frontend"; + src = myWebApp; + + buildInputs = [ pkgs.nodePackages.gulp ]; + + bowerComponents = pkgs.buildBowerComponents { <co xml:id="ex-buildBowerComponentsDefault-1" /> + name = "my-web-app"; + generated = ./bower-packages.nix; + src = myWebApp; + }; + + buildPhase = '' + cp --reflink=auto --no-preserve=mode -R $bowerComponents/bower_components . <co xml:id="ex-buildBowerComponentsDefault-2" /> + export HOME=$PWD <co xml:id="ex-buildBowerComponentsDefault-3" /> + ${pkgs.nodePackages.gulp}/bin/gulp build <co xml:id="ex-buildBowerComponentsDefault-4" /> + ''; + + installPhase = "mv gulpdist $out"; +} +</programlisting> +``` + +A few notes about [Full example — `default.nix`](#ex-buildBowerComponentsDefaultNix): + +```{=docbook} +<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> +``` + +## Troubleshooting {#ssec-bower2nix-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/bower.xml b/doc/languages-frameworks/bower.xml deleted file mode 100644 index b0738cad293b..000000000000 --- a/doc/languages-frameworks/bower.xml +++ /dev/null @@ -1,196 +0,0 @@ -<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> - 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> - - <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> -<programlisting language="json"> -<![CDATA[{ - "name": "my-web-app", - "dependencies": { - "angular": "~1.5.0", - "bootstrap": "~3.3.6" - } -}]]> -</programlisting> - </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 = [ - (fetchbower "angular" "1.5.3" "~1.5.0" "1749xb0firxdra4rzadm4q9x90v6pzkbd7xmcyjk6qfza09ykk9y") - (fetchbower "bootstrap" "3.3.6" "~3.3.6" "1vvqlpbfcy0k5pncfjaiskj3y6scwifxygfqnw393sjfxiviwmbv") - (fetchbower "jquery" "2.2.2" "1.9.1 - 2" "10sp5h98sqwk90y4k6hbdviwqzvzwqf47r3r51pakch5ii2y7js1") -]; }]]> -</programlisting> - </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> - - <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> -<programlisting language="nix"> -bowerComponents = buildBowerComponents { - name = "my-web-app"; - generated = ./bower-packages.nix; <co xml:id="ex-buildBowerComponents-1" /> - src = myWebApp; <co xml:id="ex-buildBowerComponents-2" /> -}; -</programlisting> - </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> -<programlisting language="javascript"> -<![CDATA[var gulp = require('gulp'); - -gulp.task('default', [], function () { - gulp.start('build'); -}); - -gulp.task('build', [], function () { - console.log("Just a dummy gulp build"); - gulp - .src(["./bower_components/**/*"]) - .pipe(gulp.dest("./gulpdist/")); -});]]> -</programlisting> - </example> - - <example xml:id="ex-buildBowerComponentsDefaultNix"> - <title>Full example — <filename>default.nix</filename></title> -<programlisting language="nix"> -{ myWebApp ? { outPath = ./.; name = "myWebApp"; } -, pkgs ? import <nixpkgs> {} -}: - -pkgs.stdenv.mkDerivation { - name = "my-web-app-frontend"; - src = myWebApp; - - buildInputs = [ pkgs.nodePackages.gulp ]; - - bowerComponents = pkgs.buildBowerComponents { <co xml:id="ex-buildBowerComponentsDefault-1" /> - name = "my-web-app"; - generated = ./bower-packages.nix; - src = myWebApp; - }; - - buildPhase = '' - cp --reflink=auto --no-preserve=mode -R $bowerComponents/bower_components . <co xml:id="ex-buildBowerComponentsDefault-2" /> - export HOME=$PWD <co xml:id="ex-buildBowerComponentsDefault-3" /> - ${pkgs.nodePackages.gulp}/bin/gulp build <co xml:id="ex-buildBowerComponentsDefault-4" /> - ''; - - 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> - The actual build command. Other tools could be used. - </para> - </callout> - </calloutlist> - </para> - </section> - - <section xml:id="ssec-bower2nix-troubleshooting"> - <title>Troubleshooting</title> - - <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> - </listitem> - </varlistentry> - </variablelist> - </section> -</section> diff --git a/doc/languages-frameworks/index.xml b/doc/languages-frameworks/index.xml index 0d016b660bdf..bfb05626cc34 100644 --- a/doc/languages-frameworks/index.xml +++ b/doc/languages-frameworks/index.xml @@ -8,7 +8,7 @@ <xi:include href="agda.section.xml" /> <xi:include href="android.section.xml" /> <xi:include href="beam.section.xml" /> - <xi:include href="bower.xml" /> + <xi:include href="bower.section.xml" /> <xi:include href="coq.section.xml" /> <xi:include href="crystal.section.xml" /> <xi:include href="emscripten.section.xml" /> |