| |
@@ -1,21 +1,28 @@
|
| |
= Node.js Packaging Guidelines
|
| |
|
| |
- == Naming Guidelines
|
| |
+ The upstream Node.js stance on https://nodejs.org/en/blog/npm/npm-1-0-global-vs-local-installation/[global library packages] is that they are ".. best avoided if not needed." In Fedora, we take the same stance with our nodejs packages. You can provide a package that uses nodejs, but you should bundle all the nodejs libraries that are needed.
|
| |
|
| |
- * The name of a Node.js extension/library package must start with _nodejs-_ then the upstream name or name used in the npm registry. For example: _nodejs-foomodule_. While it is uncommon for a package's name to contain _node_, if it does, you should still add the nodejs prefix. For instance, the npm registry contains a _uuid_ and a _node-uuid_ module, which would need to be named _nodejs-uuid_ and _nodejs-node-uuid_, repsectively.
|
| |
+ == What to Package
|
| |
+
|
| |
+ * The interpreter, development headers/libraries, and the assorted tools to manage project-level installations.
|
| |
+ ** Examples: nodejs, npm, yarn
|
| |
+ * Packages that provide applications that users would want to use in their shell.
|
| |
+ ** Examples: uglify
|
| |
+
|
| |
+ == Naming Guidelines
|
| |
|
| |
* Application packages that mainly provide tools (as opposed to libraries) that happen to be written for Node.js must follow the general xref:Naming.adoc[Naming Guidelines] instead.
|
| |
|
| |
+ * The name of a Node.js extension/library package must start with _nodejs-_ then the upstream name or name used in the npm registry. For example: _nodejs-foomodule_. While it is uncommon for a package's name to contain _node_, if it does, you should still add the nodejs prefix. For instance, the npm registry contains a _uuid_ and a _node-uuid_ module, which would need to be named _nodejs-uuid_ and _nodejs-node-uuid_, repsectively.
|
| |
+
|
| |
== BuildRequires
|
| |
|
| |
- To build a package containing pure JavaScript node modules, you need to have:
|
| |
+ To build a package that is a nodejs module, bundles or uses nodejs modules, or needs nodejs for building or testing, you need to have:
|
| |
|
| |
....
|
| |
- BuildRequires: nodejs
|
| |
+ BuildRequires: nodejs-devel
|
| |
....
|
| |
|
| |
- Additional BuildRequires are necessary for native modules. See <<Building native modules with node-gyp>> for more information.
|
| |
-
|
| |
== Macros
|
| |
|
| |
The following macros are defined for you:
|
| |
@@ -47,6 +54,41 @@
|
| |
|
| |
Using this macro instead of hardcoding the directory in the specfile ensures your spec remains compatible with the installed Node.js version even if the directory structure changes radically (for instance, if `+%nodejs_sitelib+` moves into `+%{_datadir}+`).
|
| |
|
| |
+ == ExclusiveArch
|
| |
+
|
| |
+ The V8 JavaScript runtime used by Node.js uses a Just-in-Time (JIT) compiler that is specially tuned to individual architectures, and must be manually ported to any new architectures that wish to support it. Node.js packages must include an ExclusiveArch line that restricts them to only these architectures.
|
| |
+
|
| |
+ The `+%{nodejs_arches}+` macro is provided to make this easy, so pure JavaScript packages must use:
|
| |
+
|
| |
+ ....
|
| |
+ ExclusiveArch: %{nodejs_arches} noarch
|
| |
+ ....
|
| |
+
|
| |
+ Native (binary) packages must omit `+noarch+` and list only `+%{nodejs_arches}+` or the list of architectures as appropriate.
|
| |
+
|
| |
+ == Bundled Licenses
|
| |
+
|
| |
+ The licenses of the bundled Node.js modules need to be in the spec file. If you are using our bundling script they will be listed in <package>-<version>-bundled-licenses.txt. It is recommended that you include <package>-<version>-bundled-licenses.txt in your rpm
|
| |
+
|
| |
+ Each time you update your package, you need to verify the bundled licenses against https://fedoraproject.org/wiki/Licensing:Main#Software_License_List[Fedoras Software License List].
|
| |
+
|
| |
+ List all unuique licenses on the License: line of your spec file. https://fedoraproject.org/wiki/Licensing:FAQ?rd=Licensing/FAQ#How_should_I_handle_multiple_licensing_situations.3F[Seperate each license with the word "and"]
|
| |
+
|
| |
+ ....
|
| |
+ License: <license1> and <license2> and <license3>
|
| |
+ ...
|
| |
+ Source3: %{npm_name}-%{version}-bundled-licenses.txt
|
| |
+ ...
|
| |
+ %prep
|
| |
+ ...
|
| |
+ cp %{SOURCE3} .
|
| |
+ ...
|
| |
+ %files
|
| |
+ %license LICENSE %{npm_name}-%{version}-bundled-licenses.txt
|
| |
+ ....
|
| |
+
|
| |
+ If you have further questions refer to the https://docs.fedoraproject.org/en-US/packaging-guidelines/LicensingGuidelines/[Fedora Licensing Guidelines]
|
| |
+
|
| |
== Using tarballs from the npm registry
|
| |
|
| |
The canonical method for shipping most node modules is tarballs from the npm registry. The `+Source0+` for such modules should be of the form http://registry.npmjs.org/[`+http://registry.npmjs.org/+`]`+/-/+``+-+``+.tgz+`. For instance:
|
| |
@@ -64,21 +106,58 @@
|
| |
%setup -q -n package
|
| |
....
|
| |
|
| |
- == ExclusiveArch
|
| |
+ == Using tarballs for bundling
|
| |
|
| |
- The V8 JavaScript runtime used by Node.js uses a Just-in-Time (JIT) compiler that is specially tuned to individual architectures, and must be manually ported to any new architectures that wish to support it. Node.js packages must include an ExclusiveArch line that restricts them to only these architectures.
|
| |
+ It is prefered to use tarballs for bundling node module dependencies. These tarballs should be independent from the main package source. There should be two tarballs. One for the binary, runtime package. One for testing while the package builds. This creates a smaller installed package.
|
| |
|
| |
- The `+%{nodejs_arches}+` macro is provided to make this easy, so pure JavaScript modules must use:
|
| |
+ These tarballs store the bundled modules in a directory called node_modules_prod, and node_modules_dev.
|
| |
+
|
| |
+ If your packages does not need one of the tarballs, then change these instructions accordingly. If it does not need the prod tarball, remove `+Source1+` plus the `+%build+` and `+%install+` sections. If it does not need the dev tarball, remove `+Source2+` and the `+%check+` section.
|
| |
+
|
| |
+ Note1: The setup of the prod and dev tarballs will soon become a macro. At the time of this writting, they are not.
|
| |
+
|
| |
+ Note2: The tarball with the dev dependencies needs to be unpacked in %check and not in %prep to avoid accidentally bundling the unpackaged dependencies that are only needed for testing.
|
| |
|
| |
....
|
| |
- ExclusiveArch: %{nodejs_arches} noarch
|
| |
+ ...
|
| |
+ Source1: %{npm_name}-%{version}-nm-prod.tgz
|
| |
+ Source2: %{npm_name}-%{version}-nm-dev.tgz
|
| |
+ ...
|
| |
+ %prep
|
| |
+ ...
|
| |
+ # Setup bundled runtime(prod) node modules
|
| |
+ tar xfz %{SOURCE1}
|
| |
+ mkdir -p node_modules
|
| |
+ pushd node_modules
|
| |
+ ln -s ../node_modules_prod/* .
|
| |
+ ln -s ../node_modules_prod/.bin .
|
| |
+ popd
|
| |
+ ...
|
| |
+ %install
|
| |
+ ...
|
| |
+ # Copy over bundled nodejs modules
|
| |
+ cp -pr node_modules node_modules_prod %{buildroot}%{nodejs_sitelib}/%{npm_name}
|
| |
+ ...
|
| |
+ %check
|
| |
+ %{__nodejs} -e 'require("./")'
|
| |
+ # Setup bundled dev node_modules for testing
|
| |
+ # Note: this cannot be in %%prep or the dev node_modules
|
| |
+ # can get pulled into the regular rpm
|
| |
+ tar xfz %{SOURCE2}
|
| |
+ pushd node_modules
|
| |
+ ln -s ../node_modules_dev/* .
|
| |
+ popd
|
| |
+ pushd node_modules/.bin
|
| |
+ ln -s ../../node_modules_dev/.bin/* .
|
| |
+ popd
|
| |
+ # Example test run using the binary in ./node_modules/.bin/
|
| |
+ ./node_modules/.bin/vows --spec --isolate
|
| |
+ ...
|
| |
....
|
| |
|
| |
- Native (binary) modules must omit `+noarch+` and list only `+%{nodejs_arches}+` or the list of architectures as appropriate.
|
| |
-
|
| |
== Installing Modules
|
| |
|
| |
- Most node modules do not contain their own install mechanism. Instead they rely on `+npm+` to do it for them. `+npm+` *must not* be used to install modules in Fedora packages, since it usually requires network access, always tries to bundle libraries, and installs files in a manner inconsistent with the Filesystem Hierarchy Standard (FHS).
|
| |
+ Most node modules do not contain their own install mechanism. Instead they rely on `+npm+` to do it for them. `+npm+` *must not* be used to install modules in Fedora packages, since it usually requires network access.
|
| |
|
| |
Instead, install files in their proper place manually using `+install+` or `+cp+`. Most files should be installed in `+%{nodejs_sitelib}/+` but documentation should be installed via `+%doc+`. In the event that the module ships arch independent content other than JavaScript code, that content should be installed in `+%{_datadir}+` and the module should be patched to cope with that.
|
| |
|
| |
@@ -88,14 +167,21 @@
|
| |
|
| |
== Automatic Requires and Provides
|
| |
|
| |
- The _nodejs_ package includes an automatic Requires and Provides generator that automatically adds versioned dependencies based on the information provided in a module's _package.json_ file. Additional Requires are added to native (binary) modules to protect against ABI breaks in Node or the V8 JavaScript runtime.
|
| |
+ The _nodejs_ package includes an automatic Requires and Provides generator that automatically adds versioned dependencies based on the information provided in a module's and bundled dependencies _package.json_ file. Additional Requires are added to native (binary) modules to protect against ABI breaks in Node or the V8 JavaScript runtime. Additional Provides: bundled() line is added for e
|
| |
+
|
| |
|
| |
- === Provides
|
| |
+ === Provides npm
|
| |
|
| |
It also adds virtual provides in the form `+npm(+``+)+` to identify modules listed in the npm registry (the module is listed at npmjs.org) . If a module is not listed in the npm registry, it must not provide this. Modules that aren't listed in the npm registry should set `+private+` to `+true+` in their `+package.json+` file. If not, you must patch `+package.json+` to include that.
|
| |
|
| |
+ === Provides bundled
|
| |
+
|
| |
+ It also automatically adds bundled provides in the form `+bundled(<bundled_module_name>) = <bundled_module_version>+` to identify bundled modules. Bundled modules must be in either the node_modules or node_modules_prod directories to be automatically added.
|
| |
+
|
| |
=== Correcting Dependencies
|
| |
|
| |
+ For non-bundled modules only.
|
| |
+
|
| |
Occasionally the dependencies listed in package.json are inaccurate. For instance, the module may work with a newer version of a dependency than the one explictly listed in the _package.json_ file. To correct this, use the `+%nodejs_fixdep+` RPM macro. This macro should be used in `+%prep+` and will patch _package.json_ to contain the correct dependency information.
|
| |
|
| |
To convert any dependency to not list a specific version, just call `+%nodejs_fixdep+` with the npm module name of the dependency. This changes the version in _package.json_ to `+*+`. (Or adds one if it wasn't already listed.) For example:
|
| |
@@ -126,13 +212,9 @@
|
| |
|
| |
== Symlinking Dependencies
|
| |
|
| |
- Node.js and npm require that dependencies explicitly be included or linked into a _node_modules_ directory inside the module directory. To make this easier, a `+%nodejs_symlink_deps+` macro is provided and will automatically create a _node_modules_ tree with symlinks for each dependency listed in _package.json_. This macro should be called in the `+%install+` section of every Node.js module package.
|
| |
+ For non-bundled modules only.
|
| |
|
| |
- == Removing bundled modules
|
| |
-
|
| |
- Some node modules contain copies of other libraries in their source tree. You must remove these in `+%prep+`. Simply running `+rm -rf node_modules+` is sufficient for most modules.
|
| |
-
|
| |
- `+%nodejs_symlink_deps+` outputs a warning when a _node_modules_ directory already exists in the `+%buildroot+`, and will fail if it cannot create a symlink because a directory for it already exists.
|
| |
+ Node.js and npm require that dependencies explicitly be included or linked into a _node_modules_ directory inside the module directory. To make this easier, a `+%nodejs_symlink_deps+` macro is provided and will automatically create a _node_modules_ tree with symlinks for each dependency listed in _package.json_. This macro should be called in the `+%install+` section of every Node.js module package.
|
| |
|
| |
== Building native modules with node-gyp
|
| |
|
| |
@@ -185,12 +267,6 @@
|
| |
|
| |
If the module uses it's own Makefiles to locate the shared object file(s) to a specific location, then those files should installed in that location.
|
| |
|
| |
- === Dealing with Bundled Libraries
|
| |
-
|
| |
- Many native modules contain bundled copies of libraries already present in Fedora. You must build against the system version of these libraries. For more information, see xref:index.adoc#bundling[Bundled Libraries Guidelines].
|
| |
-
|
| |
- The Fedora version of `+node-gyp+` will handle the fact that shared versions of libuv, v8, and http_parser without modification to the module, since `+node-gyp+` always unconditionally configures these libraries. However, some modules may rely on other libraries bundled with node, such as openssl or c-ares. These may need to be patched to use the system headers for these libraries.
|
| |
-
|
| |
=== Filtering Unwanted Provides
|
| |
|
| |
RPM automatically adds some unwanted virtual provides to the shared object files included with native modules. To remove them, add `+%{?nodejs_default_filter}+` to the top of the package's spec file. For more information, see xref:AutoProvidesAndRequiresFiltering.adoc[Packaging:AutoProvidesAndRequiresFiltering].
|
| |
@@ -209,14 +285,86 @@
|
| |
|
| |
For convienence, %nodejs_symlink_deps also accepts a `+--check+` argument, which will make it operate in the current working directory instead of the buildroot. You can use this in the `+%check+` section to make dependencies available for running tests. When this argument is used, development dependencies as listed in the "devDependencies" key in _package.json_ are also linked.
|
| |
|
| |
- == Handling Multiple Version Scenarios
|
| |
+ == Bundling Script
|
| |
+
|
| |
+ It is recommended to use the nodejs-packaging-bundler script found in the Fedora nodejs-packaging-bundler package. More documentation for it can be found at the https://src.fedoraproject.org/rpms/nodejs-packaging/[_Fedora nodejs-packaging repo] .
|
| |
+
|
| |
+ == Example Spec
|
| |
|
| |
- Occasionally, there may be an update to a Node.js module that involves backwards-incompatible changes. In such situations, it may be necessary to ship a compatibility package with the older version to allow time for dependencies to migrate to the new version. The Requires generator and `+%nodejs_symlink_deps+` contain logic that handles such situations transparently for packages that depend on these modules. No special action is required for other modules that depend on multiply-versioned modules that already exist.
|
| |
+ ....
|
| |
+ %global npm_name tape
|
| |
+
|
| |
+ Name: nodejs-%{npm_name}
|
| |
+ Version: 5.1.1
|
| |
+ Release: 1%{?dist}
|
| |
+ Summary: Tap-producing test harness for Node.js and browsers
|
| |
+
|
| |
+ License: MIT and ICS
|
| |
+ URL: https://github.com/substack/tape
|
| |
+ Source0: http://registry.npmjs.org/%{npm_name}/-/%{npm_name}-%{version}.tgz
|
| |
+ Source1: %{npm_name}-%{version}-nm-prod.tgz
|
| |
+ Source2: %{npm_name}-%{version}-nm-dev.tgz
|
| |
+ Source3: %{npm_name}-%{version}-bundled-licenses.txt
|
| |
+
|
| |
+ BuildArch: noarch
|
| |
+ ExclusiveArch: %{nodejs_arches} noarch
|
| |
+
|
| |
+ Requires: nodejs
|
| |
+ BuildRequires: nodejs-devel
|
| |
|
| |
- However, the actual multiply-versioned packages require special attention in order for this to work. To implement this, first contact the https://admin.fedoraproject.org/mailman/listinfo/nodejs[Node.js SIG mailing list], explain the situation, and include the npm module name of the affected package. The `+nodejs-packaging+` maintainers will then add it to the `+/usr/share/node/multiver_modules+` file so the package is treated specially by `+%nodejs_symlink_deps+`.
|
| |
+ %description
|
| |
+ %{summary}.
|
| |
|
| |
- Then, in both the original package and the compatibility package, change the `+%install+` section to install the module into a versioned directory in `+%{nodejs_sitelib}+` of the form `+@+`. For instance, the 2.x `+uglify-js+` module should install into `+uglify-js@2+`.
|
| |
|
| |
- One of the packages must additionally provide a symlink from the usual location to the versioned location described above. For instance, `+%{nodejs_sitelib}/uglify-js+` would point to `+%{nodejs_sitelib}/uglify-js@2+` in the previous example. Typically the newest package should provide this symlink, but it might be prudent for the older version to provide it instead when introducing such a package into an existing Fedora release, so as not to break dependent packages. The symlink can then be migrated to the newest version in the next Fedora release.
|
| |
+ %prep
|
| |
+ %setup -q -n package
|
| |
+ cp %{SOURCE3} .
|
| |
+ # Setup bundled runtime(prod) node modules
|
| |
+ tar xfz %{SOURCE1}
|
| |
+ mkdir -p node_modules
|
| |
+ pushd node_modules
|
| |
+ ln -s ../node_modules_prod/* .
|
| |
+ ln -s ../node_modules_prod/.bin .
|
| |
+ popd
|
| |
+
|
| |
+ %build
|
| |
+ #nothing to do
|
| |
|
| |
- Finally, any packages that depend on a version that *does not* provide the aforementioned symlink from the base name to the versioned directory must be rebuilt in order to work properly. To obtain a list of potentially affected packages, run `+repoquery --whatrequires 'npm(module_name)'+` or `+npm view module_name dependencies+`. Please coordinate with the Node.js SIG if any rebuilds are necessary.
|
| |
+ %install
|
| |
+ mkdir -p %{buildroot}%{nodejs_sitelib}/%{npm_name}
|
| |
+ cp -pr package.json index.js lib/ \
|
| |
+ %{buildroot}%{nodejs_sitelib}/%{npm_name}
|
| |
+ # Copy over bundled nodejs modules
|
| |
+ cp -pr node_modules node_modules_prod \
|
| |
+ %{buildroot}%{nodejs_sitelib}/%{npm_name}
|
| |
+
|
| |
+ mkdir -p %{buildroot}%{nodejs_sitelib}/tape/bin
|
| |
+ install -p -D -m0755 bin/tape %{buildroot}%{nodejs_sitelib}/tape/bin/tape
|
| |
+ mkdir -p %{buildroot}%{_bindir}
|
| |
+ ln -sf %{nodejs_sitelib}/tape/bin/tape %{buildroot}%{_bindir}/tape
|
| |
+
|
| |
+ %check
|
| |
+ %{__nodejs} -e 'require("./")'
|
| |
+ # Setup bundled dev node_modules for testing
|
| |
+ # Note: this cannot be in %%prep or the dev node_modules
|
| |
+ # can get pulled into the regular rpm
|
| |
+ tar xfz %{SOURCE2}
|
| |
+ pushd node_modules
|
| |
+ ln -s ../node_modules_dev/* .
|
| |
+ popd
|
| |
+ pushd node_modules/.bin
|
| |
+ ln -s ../../node_modules_dev/.bin/* .
|
| |
+ popd
|
| |
+ # Run tests
|
| |
+ ./node_modules/.bin/tap test/*.js
|
| |
+
|
| |
+
|
| |
+ %files
|
| |
+ %doc readme.markdown
|
| |
+ %license LICENSE %{npm_name}-%{version}-bundled-licenses.txt
|
| |
+ %{nodejs_sitelib}/tape
|
| |
+ %{_bindir}/tape
|
| |
+
|
| |
+
|
| |
+ %changelog
|
| |
+ ....
|
| |
tdawson
commented 3 years ago
This change goes along with the Stop Shipping Individual Nodejs Library Packages change request.
https://fedoraproject.org/wiki/Changes/NodejsLibrariesBundleByDefault
Signed-off-by: Troy Dawson tdawson@redhat.com