Просмотр исходного текста страницы Node.js policy

=== Naming ===
* 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: {{pkg|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 {{pkg|nodejs-uuid}} and {{pkg|nodejs-node-uuid}}, repsectively.

* Application packages that mainly provide tools (as opposed to libraries) that happen to be written for Node.js must follow the general naming guidelines instead.

== BuildRequires ==
To build a package containing pure JavaScript node modules, you need to have:
<pre>
BuildRequires: nodejs-packaging
</pre>

Additional BuildRequires are necessary for native modules. See [[#Building native modules with node-gyp]] for more information.

== Macros ==
In ROSA, the following macros are defined for you:

{| class="wikitable"
!Macro!!Normal Definition!!Notes
|-
|__nodejs||%{_bindir}/node||The Node.js interpreter
|-
|nodejs_version||e.g. 0.9.5||The currently installed version of Node.js.
|-
|nodejs_sitelib||%{_prefix}/lib/node_modules||Where Node.js modules written purely in JavaScript are installed
|-
|nodejs_sitearch||%{_prefix}/lib/node_modules||Where native C++ Node.js modules are installed
|-
|nodejs_symlink_deps||%{_prefix}/lib/rpm/nodejs-symlink-deps||See [[#Symlinking Dependencies]] below.
|-
|nodejs_fixdep||%{_prefix}/lib/rpm/nodejs-fixdep||See [[#Correcting Dependencies]]
|-
|nodejs_default_filter||%global __provides_exclude_from ^%{nodejs_sitearch}/.*\\.node$||Filters unwanted provides from native modules. See [[#Filtering Unwanted Provides]] below.
|}

These macros are provided by the ''nodejs-packaging'' package.

During {{macro|%install}} or when listing {{macro|%files}} you can use the {{macro|%nodejs_sitelib}} or {{macro|%nodejs_sitearch}} macro to specify where the installed modules are to be found. For instance:

<pre>
%files
# A pure JavaScript node module
%{nodejs_sitelib}/foomodule/
# A native node module
%{nodejs_sitearch}/barmodule/
</pre>

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 {{macro|%nodejs_sitelib}} moves into {{macro|%{_datadir}}}).

== Using tarballs from the npm registry ==

The canonical method for shipping most node modules is tarballs from the npm registry. The <code>Source0</code> for such modules should be of the form <code>http://registry.npmjs.org/<modulename>/-/<modulename>-<version>.tgz</code>.  For instance:

<pre>
Source0:  http://registry.npmjs.org/npm/-/npm-1.1.70.tgz
</pre>

This method should be preferred to using checkouts from git or automatically generated tarballs from GitHub.

These tarballs store the contents of the module inside a <code>package</code> directory, so every package using these tarballs should use the following in {{macro|%prep}}:

<pre>
%prep
%setup -q -n package
</pre>

{{Примечание|'''Verifying hashes'''. The SHA1SUM of tarballs delivered by the npm registry is available as the dist['shasum'] JSON property of the npm metadata for the module, which can be obtained by visiting ''http://registry.npmjs.org/<modulename>/<version>''}}

== Installing Modules ==

Most node modules do not contain their own install mechanism.  Instead they rely on <code>npm</code> to do it for them.  <code>npm</code> '''must not''' be used to install modules in ROSA 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).

Instead, install files in their proper place manually using <code>install</code> or <code>cp</code>. Most files should be installed in <code>%{nodejs_sitelib}/<npm module name></code> but documentation should be installed via <code>%doc</code>.  In the event that the module ships arch independent content other than JavaScript code, that content should be installed in <code>%{_datadir}</code> and the module should be patched to cope with that.

=== Client-side JavaScript ===
Many node modules contain JavaScript that can be used both client-side and server-side and it is sometimes hard to identify code intended only for use in the browser.  Since there are no current packaging guidelines for client-side JavaScript and bundling of such code is currently permitted in ROSA, it is currently permissible for client-side JavaScript to be bundled with nodejs modules in <code>%{nodejs_sitelib}</code>.

{{Примечание|These exceptions will probably go away. With the introduction of Node.js into ROSA it is likely that standards for client-side JavaScript will be established and the bundling exception for client-side JavaScript will be removed.  Many client-side JavaScript technologies use node in some way or use node modules as the canonical method of distribution (sometimes alongside code intended to be used with node) so such guidelines must certainly take Node.js into account.  At this time, node module packages will be expected to conform to these guidelines, possibly shipping the client-side and server-side portions separately.}}

== 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.

=== Provides ===

It also adds virtual provides in the form <code>npm(<module name>)</code> 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 <code>private</code> to <code>true</code> in their <code>package.json</code> file. If not, you must patch <code>package.json</code> to include that.

=== Correcting Dependencies ===
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 <code>%nodejs_fixdep</code> RPM macro. This macro should be used in <code>%prep</code> and will patch ''package.json'' to contain the correct dependency information.

{{Примечание|Always fix ''package.json''. RPM macros like <code>%nodejs_symlink_deps</code> rely on accurate information in ''package.json'' to work properly, as does the Node.js interpreter and npm at runtime.}}

To convert any dependency to not list a specific version, just call <code>%nodejs_fixdep</code> with the npm module name of the dependency. This changes the version in ''package.json'' to <code>*</code>. (Or adds one if it wasn’t already listed.) For example:

<pre>
%prep
%setup -q -n package
%nodejs_fixdep foomodule
</pre>

You can also specify a version:

<pre>
%prep
%setup -q -n package
%nodejs_fixdep foomodule '>2.0'
</pre>

The second argument to <code>%nodejs_fixdep</code> must be a valid ''package.json'' version specifier as explained in [https://npmjs.org/doc/json.html <code>`man npm json`</code>].

You can also remove a dependency:

<pre>
%prep
%setup -q -n package
%nodejs_fixdep -r foomodule
</pre>

{{Примечание|Remember that you should always send patches or bugs upstream when correcting dependencies for packages.}}

== 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 <code>%nodejs_symlink_deps</code> 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 <code>%install</code> section of every Node.js module package.

{{Примечание|'''Include even in modules without dependencies.''' While it isn't strictly necessary in modules that don't have dependencies, include it anyway so you don't have to worry about adding it if the package adds dependencies in the future.}}

=== %check ===

For convienence, %nodejs_symlink_deps also accepts a <code>--check</code> argument, which will make it operate in the current working directory instead of the buildroot. You can use this in the <code>%check</code> section of RPM spec files 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.

== Removing bundled modules ==
Some node modules contain copies of other libraries in their source tree. You must remove these in <code>%prep</code>. Simply running <code>rm -rf node_modules</code> is sufficient for most modules.

<code>%nodejs_symlink_deps</code> outputs a warning when a ''node_modules'' directory already exists in the <code>%buildroot</code>, and will fail if it cannot create a symlink because a directory for it already exists.

== Building native modules with node-gyp ==

Most native modules use the <code>node-gyp</code> tool to build themselves, which configures and uses the <code>gyp</code> build framework to build addon modules that can interact with Node.js and the V8 JavaScript interpreter used by it.

The WAF build framework has been abandoned by upstream and is not supported in ROSA.

=== BuildRequires ===

To build a native module designed to be built with node-gyp, add the following lines to your spec:
<pre>
BuildRequires: node-gyp
BuildRequires: nodejs
</pre>

and ''-devel'' packages for any shared libraries needed by the module.

=== %build ===

Some native modules have Makefiles or other build processes that handle any special needs that module has, such as linking to system versions of dependencies. If present, these should be used. Check the module’s ''package.json'' file for information about what command npm will run to build these modules.

Most modules use vanilla node-gyp, and may not have build instructions in ''package.json''. To build these, simply use the following:

<pre>
%build
export CXXFLAGS="%{optflags}"
node-gyp rebuild
</pre>

Note that some modules may specify something like <code>node-gyp configure && node-gyp build</code>. This is equivalent to <code>node-gyp rebuild</code>.

=== %install ===

<code>node-gyp</code> creates a shared object file with the extension <code>.node</code> as part of its build process, which should be located in <code>build/Release</code>. This file may be used as the main entry point for the library, or is utilized by JavaScript wrapper code included with the module.

{{Примечание|'''Identifying whether a module contains JavaScript wrapper code'''. The easiest way to identify whether a module contains JavaScript wrapper code is simply to check for the existence of JavaScript (<code>.js</code>) files in the tarball that are used in a library context (i.e. make sure they aren't just used for tests or other ancillary purposes).  You can also check if the main entrypoint is defined in ''package.json'' in the <code>main</code> property.}}

If the shared object is used as the main entry point, it should be installed at <code>%{nodejs_sitelib}/<module name>/index.node</code>. The `require()` function will automatically load this if there is no corresponding `index.js` or entry point defined in ''package.json'' to override it. For example:

<pre>
%install
mkdir -p %{buildroot}%{nodejs_sitelib}/foomodule
cp -p build/Release/index.node package.json %{buildroot}%{nodejs_sitelib}/foomodule/
</pre>

If the shared object is called by JavaScript wrapper code, the situation is slightly more complicated.

If the module uses the npm [https://npmjs.org/package/bindings ''bindings''] module, the shared object file should be installed in <code>%{nodejs_sitelib}/<module name>/build/<module name>.node</code>, which is at the top of ''bindings''' search path and where <code>node-gyp</code> usually creates a symlink to wherever the real shared object file exists. For example:

<pre>
%install
mkdir -p %{buildroot}%{nodejs_sitelib}/foomodule/build
cp -p package.json wrapper.js %{buildroot}%{nodejs_sitelib}/foomodule/
cp -p build/Release/foomodule.node %{buildroot}%{nodejs_sitelib}/foomodule/build/
</pre>

If the module hardcodes <code>build/Release/<module name>.node</code>, the module should be patched to use <code>build/<module name>.node</code> instead, and upstream should be advised that they should use the ''bindings'' module, because their module could break when users use debug builds of node.

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.

{{Примечание|Don't install unnecessary development files. <code>npm</code> will leave C++ source files, object (<code>.o</code>) files, etc. in the module directory after installing it.  These files '''must not''' be installed in ROSA packages.}}

=== Dealing with Bundled Libraries ===

Many native modules contain bundled copies of libraries already present in ROSA. You must build against the system version of these libraries.

The ROSA version of <code>node-gyp</code> will handle the fact that shared versions of libuv, v8, and http_parser without modification to the module, since <code>node-gyp</code> 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 <code>%{?nodejs_default_filter}</code> to the top of the package’s spec file.

== Handling Multiple Version Scenarios ==

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 <code>%nodejs_symlink_deps</code> 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.

{{Примечание|This only works with the major version. The [http://semver.org/ semantic versioning specification] used by npm requires that the major version be incremented when backwards-incompatible changes are introduced.  Therefore, ROSA currently only supports multiply-versioned packages where the major version is different.  If upstream introduces breaking changes in a minor release, please notify them that they are violating npm's conventions and ask that they bump the major version.}}

However, the actual multiply-versioned packages require special attention in order for this to work. To implement this, first contact the rosa-devel mailing list, explain the situation, and include the npm module name of the affected package. The <code>nodejs-packaging</code> maintainers will then add it to the <code>/usr/share/node/multiver_modules</code> file so the package is treated specially by <code>%nodejs_symlink_deps</code>.

Then, in both the original package and the compatibility package, change the <code>%install</code> section to install the module into a versioned directory in <code>%{nodejs_sitelib}</code> of the form <code><npm_name>@<major_version></code>. For instance, the 2.x <code>uglify-js</code> module should install into <code>uglify-js@2</code>.

{{Примечание|'''What's with the <code>@</code>?''' npm uses the <code>@</code>-sign to differentiate versions in its commands.  For instance, <code>npm install uglify-js@1</code>.  Replicating this in the directory structure ensures commands like <code>npm link uglify-js@1</code> will work similarly to the way <code>npm install</code> does.}}

One of the packages must additionally provide a symlink from the usual location to the versioned location described above. For instance, <code>%{nodejs_sitelib}/uglify-js</code> would point to <code>%{nodejs_sitelib}/uglify-js@2</code> 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 ROSA release, so as not to break dependent packages. The symlink can then be migrated to the newest version in the next ROSA release.

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 <code>reqoquery --whatrequires 'npm(module_name)'</code> or <code>npm view module_name dependencies</code>. Please coordinate with the ROSA maintainers if any rebuilds are necessary.

[[Category:Packaging guidelines]]

{{Примечание|This Policy is based on the [https://fedoraproject.org/wiki/Packaging:Node.js Fedora Node.js Packaging Policy].}}