Contents
- Quickstart guides
- Step 0. Configure your environment
- Step 1. Check dependencies
- Step 2. Search for existing work
- Step 3. Preview more information
- Step 4. Create packaging files
- Step 5. Create debian source package/.dsc file (if required)
- Step 6. Build the binary package
- Step 7. Push your repo to salsa
- Step 8. Request sponsorship
- RFS Checklist
- Updating a package to a new Upstream version
- RFS mail template
- Embedding some modules
npm2deb is an automatic tool which permits to fast deploy debian/* files starting from a module downloaded via npm.
If you want help in developing:
git clone https://github.com/LeoIannacone/npm2deb
For usage information, please refer to npm2deb main page.
Quickstart guides
There is a also a more detailed tutorial with basic packaging concepts and a more structured introduction to tools and processes.
Step 0. Configure your environment
- Note 1: Make sure you do your work in debian unstable/sid. You can create either by using lxc container or docker container easily
Following commands for lxc container creation:
# apt-get install lxc # lxc-create -n deb-sid -t download -- --dist debian --release sid
See Packaging/Pre-Requisites for instructions to setup a debian sid system using different tools.
- Note 2: Make sure you setup your name and email properly in environment variables.
Add the following variables in your ~/.bashrc file. DEBEMAIL and DEBFULLNAME variables are used by debian tools to set your name and email.
export DEBEMAIL=your@email.domain export DEBFULLNAME='Your Name' alias lintian='lintian -iIEcv --pedantic --color auto' alias git-import-dsc='git-import-dsc --author-is-committer --pristine-tar' alias clean='fakeroot debian/rules clean'
Note: You can also use debclean command instead of setting alias for clean.
and update your current environment by running
source ~/.bashrc
sudo apt-get install npm2deb
Step 1. Check dependencies
Note: jade, monocle, require-directory and qw are example modules used in this document, change it with module name you want to package.
A simple workflow is check if a node_module has all dependencies already satisfied in Debian, you can use npm2deb depends to get this info.
In this example we will check jade module which at the moment is not packaged for Debian:
$ npm2deb depends -b -r jade Dependencies: NPM Debian jade (1.3.1) None ├─ monocle (1.1.51) None │ └─ readdirp (~0.2.3) node-readdirp (0.2.4-2) ├─ transformers (2.1.0) None │ ├─ uglify-js (~2.2.5) uglifyjs (1.3.5-1) │ ├─ promise (~2.0) None │ │ └─ asap (~1.0.0) None │ └─ css (~1.0.8) None │ ├─ css-stringify (1.4.1) None │ │ └─ source-map (~0.1.31) None │ │ └─ amdefine (>=0.0.4) None │ └─ css-parse (1.7.0) None ├─ character-parser (1.2.0) None ├─ mkdirp (~0.3.5) node-mkdirp (0.3.5-1) ├─ commander (2.1.0) node-commander (2.0.0-1) ├─ constantinople (~2.0.0) None │ └─ uglify-js (~2.4.0) uglifyjs (1.3.5-1) └─ with (~3.0.0) None └─ uglify-js (~2.4.12) uglifyjs (1.3.5-1)
As you can see, there are many modules not packaged for debian. npm2deb was written to reach this goal, have a tool to fast and easy package new nodejs module.
In this example we will take care about monocle module.
Step 2. Search for existing work
First of all, use npm2deb search to know if someone else has already started working on this module:
$ npm2deb search monocle Looking for similiar package: None Looking for existing repositories: None Looking for wnpp bugs: None
As you can see, there no info about monocle in Debian. So you can start to work on.
Step 3. Preview more information
Use npm2deb view command to get a preview information about module:
$ npm2deb view monocle Name: monocle Version: 1.1.51 Description: a tool for watching directories for file changes Homepage: https://github.com/samccone/monocle License: BSD Debian: None
License is automatically recognized as BSD, if this does not happen, please pass --upstream-license option during creation to set a correct license.
Step 4. Create packaging files
Next step, make the debianization:
$ npm2deb create monocle This is not a crystal ball, so please take a look at auto-generated files. You may want fix first these issues: monocle/node-monocle/debian/control: FIX_ME long description
This command creates <module_name>/node-<module_name>/debian directory which contains the basic information about the module.
You have to fix every occurrence of FIX_ME in those files.
By default npm2deb set Vcs-* fields to ?git in pkg-javascript. For more information about git, please read GitPackaging.
Note: If the module is using any complex build tools like grunt, gulp, babel, webpack, browserify or rollup (look in the devDependencies section of package.json), follow Javascript/Nodejs#Using_build_tools_like_grunt.
Manually download upstream sources (if required)
Note The node module we use here is 'require-directory'.
Follow these steps if you got this warning where uscan does not work because the upstream repo is missing tags.
*** Warning *** Using fakeupstream to download npm dist tarballs, because upstream git repo is missing tags. Its better to ask upstream to tag their releases instead of using npm dist tarballs as dist tarballs may contain pre built files and may not include tests.
Usually this can be done by uscan --verbose --download-current-version but some projects does not create git tags for their releases so we have to visit their home page (given in 'debian/control') and find out the commit for the release (from their 'commits' page) or download the tarball from npmjs.org.
Note: Current version of npm2deb already download orig tarballs from github if tag matching npm release is present or npm dist tarball if matching tag is missing in github. But if you need to include tests, you may follow Option 2 below to download github tarballs.
Option 1: Download via npmjs.org (npm2deb does this by default)
This is the easier method but you may not get tests in these tarballs. Also if it includes pre-built files (output of uglifyjs, babel, browserify, webpack etc), you may want to follow Option 2 below. You can skip this step if you already have the source tarball (downloaded by npm2deb create).
$ cd require-directory $ npm view require-directory dist.tarball https://registry.npmjs.org/require-directory/-/require-directory-2.1.1.tgz $ wget https://registry.npmjs.org/require-directory/-/require-directory-2.1.1.tgz
Option 2: Download via github.com commit snapshot
Note: You may also request the upstream to add the corresponding tag and wait a few days before choosing this option.
Homepage: https://github.com/troygoode/node-require-directory Commits page: https://github.com/troygoode/node-require-directory/commits/master
If you can't find the commit corresponding to a release from commits page of the project, check commit history of package.json file. The commit that bumped version is likely to be the commit corresponding to a release.
In this case 'bump to v2.1.1' commit is what we want Click on '<>' button on the right of this commit to browse repository on this commit.
'bump to v2.1.1 commit page: https://github.com/troygoode/node-require-directory/tree/cc71c23dd0c16cefd26855303c16ca1b9b50a36d
Click on the 'Clone or download' button Right click on 'Download ZIP' and copy its url
ZIP download url: https://github.com/troygoode/node-require-directory/archive/cc71c23dd0c16cefd26855303c16ca1b9b50a36d.zip
Paste the link on the terminal and change .zip to .tar.gz and use wget command to download this file and give -O option to set a different name for the downloaded file
$ cd require-directory/ $ wget -O node-require-directory-2.1.1.tgz https://github.com/troygoode/node-require-directory/archive/cc71c23dd0c16cefd26855303c16ca1b9b50a36d.tar.gz
Step 5. Create debian source package/.dsc file (if required)
Now combine the 'debian' directory we created earlier to the tar.gz file we downloaded (if ../node-require-directory-2.1.1-1.dsc is not present).
.dsc file (file with .dsc extension) is debian source package and is normally created by npm2deb create command.
Note: If you already imported dsc file to git, you can use gbp import-orig --pristine-tar ../node-require-directory-2.1.1.tgz to import the tarball, after removing the upstream/2.1.1 tag (git tag -d upstream/2.1.1) instead of uupdate.
$ cd node-require-directory $ uupdate -b ../node-require-directory-2.1.1.tgz
Switch to package directory and remove the extra line "* New upstream release" from debian/changelog in case you did uupdate.
$ cd ../node-require-directory-2.1.1 $ dch -e $ dpkg-source -b .
Step 6. Build the binary package
dpkg-buildpackage (if required)
- Now build the package if required (if ../node-require-directory_2.1.1-1_amd64.changes is not present).
$ dpkg-buildpackage
Import your package to git
It is highly recommended you import your debian source package (.dsc file) to git version control system at this point and commit your changes in git repo. This is useful to track all changes you make to the package. See the commands given below.
$ cd .. $ rm -rf node-require-directory $ gbp import-dsc --pristine-tar node-require-directory_2.1.1-1.dsc $ cd node-require-directory $ git tag -d debian/2.1.1-1
Note 1: Install git-buildpackage if you got gbp: command not found error
Note 2: When you run git commit, it will show the files that are going to be committed in the editor, check if any unfamiliar files are listed before you save the commit message (avoid git commit -m which does not give you one more option to verify)
Note 3: Commit only the files you have edited or added (verify only the required files are getting committed). Run debclean or clean before you commit to ensure files generated by dpkg-buildpackage is not committed. If you are using quilt, run quilt pop -a before commit.
# apt-get install git-buildpackage
It would be a good idea to add --pristine-tar option to gbp command as default in ~/.gbp.conf
[DEFAULT] pristine-tar = True
Generate required files
Many times the source package only has src directory and lib or dist directories may be missing. Usually you need to use commands like babeljs, rollup or other build tools. See Javascript/Nodejs#Using_build_tools_like_grunt for more tool specific tips.
If your module has some build steps documented in package.json under scripts, you will need to adapt it to debian commands and add to debian/nodejs/build
See https://salsa.debian.org/js-team/pkg-js-tools/-/blob/master/doc/tools/README.md#readme for more options of pkg-js-tools.
You will need to create debian/clean file and remove all generated files in the upstream source directory so that the next build is started from a clean state. Never use dpkg-source --commit if you did not make any changes to any upstream source files, as this result in creating patch files from the generated files.
Make your package lintian clean
$ lintian ../node-require-directory_2.1.1-1_amd64.changes
Make sure you fix all the errors and warnings (lines starting with E: or W:) shown by lintian. Every time you make a change to any file inside debian directory. Run dpkg-buildpackage and lintian commands to make sure the warning/error is actually fixed.
lintian says: source is missing
We have 3 options when we see a "source is missing" error from lintian. You have to open the file mentioned in the lintian error and decide which option from below is suitable. If the file is a single line, most likely it is a minified file and lintian is correct. In case the long line is just data in otherwise readable file, lintian is likely wrong.
The file is not a generated file and lintian is wrong, so we can add a lintian override. See Lintian for learning more about lintian and creating overrides in case lintian is wrong.
- The file is a generated file but used only for tests and we are not running tests, so just remove that file from orig.tar
- The file is generated and that is part of the actual module we want to ship, then we remove that file from orig.tar and generate it during build using commands given in package.json#scripts.
See Javascript/Repacking for removing files from orig.tar.
You can use dch -e command to edit debian/changelog, it will warn you if you make mistakes in formatting.
Use TeamUpload instead of nmu when updating existing packages.
Update copyright file
See if there are files with extra copyright notices not covered by package.json. Check in *LICENSE* README.* COPYING etc if there are other copyright holders mentioned and add them to debian/copyright.
$ licensecheck --deb-machine -r -l0 *
Update debian/copyright with any missing information.
You can also use libconfig-model-dpkg-perl (# apt-get install libconfig-model-dpkg-perl) to update debian/copyright.
$ cme update dpkg-copyright
'license-reconcile' (# apt install license-reconcile) is another good tool to check if any copyright notices are missing.
$ license-reconcile
Note: There are two variants of MIT licenses (Expat or X11), use Expat when the text matches with that of license used in Expat project. See https://opensource.stackexchange.com/questions/8585/what-is-the-different-between-mit-and-x11-license-should-the-open-source-packag
Run tests if available
Use this example commit as reference.
You can find the test command from package.json under scripts section. Note: The code snippet below is an example only and you have to look in package.json file for the module you are currently packaging to find the test command for your package.
"scripts": {
"test": "tap test"
},
You need to add the test command as a shell script in debian/tests/pkg-js/test (Create debian/tests/pkg-js directory). Note: Replace tap test with the actual test command used in the module you are packaging. You don't need to use npx for running commands in debian, all packaged tools will be available without using npx. For example, if package.json has npx mocha as test command, you only need to run mocha command.
tap test
- You need to add the test framework (mocha, node-tape, ava etc) as a build dependency.
You need to add a Testsuite: autopkgtest-pkg-nodejs line to debian/control.
Note: Some of the test dependencies like xo, nyc, standard, eslint, jshint can be ignored. If test framework is not packaged, you can skip the tests.
ITP (Intend to Package bug)
- You can use ../node-require-directory_itp.mail as template for your ITP
Set correct target distribution in changelog
Once the package is ready for upload, change distribution to unstable, you can use dch -r command for this. During freeze new upstream versions are usually uploaded to experimental.
Clean build with sbuild
See Packaging/sbuild for instructions to use sbuild.
Verify the built deb file
Check if all the required files are installed properly (look for files section in package.json) by opening the built .deb file in an archive manager (like File Roller or Ark).
- Run autopkgtest and make sure it is passing
# apt-get install autopkgtest $ sudo autopkgtest ./ --- null
For more information about Javascript Team Infrastracture please read the Javascript page.
Step 7. Push your repo to salsa
Create an account at https://salsa.debian.org/ (if you don't have an account there already).
Add ssh keys to your account at https://salsa.debian.org/profile/keys
Method 1, using salsa(1) (devscripts):
$ salsa --group js-team --desc --tagpending push_repo .
- Method 2, manually:
Create a new project at https://salsa.debian.org/projects/new and copy its ssh url.
- Add salsa as origin for your repo and push your changes.
$ git remote add origin git@salsa.debian.org:js-team/node-promzard.git $ git push -u --all --follow-tags
You should request membership to https://salsa.debian.org/js-team/ where all team maintained packages are stored.
- If you're not "maintainer" but only "developer", ask to a maintainer to create the project before pushing your work (same for both methods).
- If this is your first package and you are not yet a member of js-team group, then you can create the repo in your personal namespace by making a public fork of the team repo.
Step 8. Request sponsorship
You can send an RFS mail to debian-js mailing list after subscribing to it from https://lists.debian.org/debian-js/ (it is a high volume list, you may want to use a dedicated email address)
- If you found a sponsor, ask them to create a repo under js-team group.
RFS Checklist
Please make sure you have taken care of these common issues before sending an RFS mail.
You MUST check if the module is already packaged. Run npm2deb search before you file an ITP. Check carefully for existing package, previous work or warnings.
- Description should be good for debian standards, both in ITP and debian/control. Mention it is a dependency of ava or browserify as the case may be. Description line should be split less than 80 characters but not too small like 30 or 40. Please manually verify no FIX_ME is remaining in control, copyright or changelog.
- Make sure --pristine-tar option is given when gbp import-dsc is run
- You MUST delete the debian tag
- You MUST push all branches (master, upstream and pristine-tar)
- You MUST make your package lintian clean every time you make changes to your package
- You MUST make it build in a clean chroot using tools like sbuild every time you make a change
If tests are present and test framework is packaged, tests should be enabled in debian/tests/pkg-js/test. Check package.json for how to run the tests.
Set correct target distribution (usually unstable and during freeze experimental for new upstream versions) in changelog instead of UNRELEASED
Squash related commits (if you have to fix something after you commit) to have a clean git history, see https://www.git-tower.com/learn/git/faq/git-squash
- You should check email for the comments you receive for ITP or RFS or ftp master rejection and fix them.
- If you don't get a reply to your RFS, please wait for at least a week before sending a reminder. If you have to send a reminder please reply to the previous RFS mail instead of writing a new mail.
- You should cc/copy your ITP when you send RFS
- You MUST import your package to js-team repo on salsa if you are a member of js-team group
Updating a package to a new Upstream version
To update a pacakge to its new upstream version click this link Javascript/Nodejs/NewUpstreamUpdate
RFS mail template
Things to mention in the mail requesting sponsorship are,
- Package name
- Current version
- Status of lintian and sbuild.
- Link to your Salsa repo for the package
Following is a sample mail to request sponsorship for a package update. https://alioth-lists.debian.net/pipermail/pkg-javascript-devel/2022-June/069855.html