Baserock/ guides/ import-tool/ Using the Baserock Import tool for npm packages

Using Baserock

Community

Background

Using the Baserock Import tool for npm Packages

Before using this tutorial, you should read the import tool quickstart page. This contains instructions for installing and updating the tool.

As well as this tutorial, there is documentation in the 'README' files in the Baserock Import Git repository. Please read the main README first, to get an understanding of what the tool does and what it does not do.

The Baserock Import tool is available in Baserock 'devel' systems. See the using baserock page for how to set yourself up a devel system.

NOTE: this document is very new, as is the import tool. Please report any lies, inconsistencies, and pain points (ideally with patches to fix them!) to the mailing list. This document is templated from the rubygems tutorial; the information there is more comprehensive

Chapter 0: Preliminaries

1) Installing and updating:

See the import tool quickstart page.

2) Making the tool work:

At the moment there's one last step: the npm import tool needs some dependencies to be installed first. Anything that find_deps, to_chunk or to_lorry requires, that isn't part of the tool itself, will need to be installed in /usr/lib/node_modules (or wherever you tell the tool to look for them). At time of writing, these are async, npm, yamljs, semver and util. This step should soon be redundant as lots of things are merged.

Most of these are part of npm, so any system with nodejs running should already have these dependencies (though you will need to tell the tool where to look for them on the commandline; see below). Currently, yamljs is the only dependency you will need to install manually. Go to usr/lib, and type 'npm install yamljs'; this should install it.

After you've done this, try importing!

Chapter 1: Doing an import

3) Running the command

The command should eventually be 'baserock-import npm PACKAGE VERSION'. When you run the import tool at the moment, though, you need to change environment variables on commandline, to tell the tool where to look for its dependencies.

eg: To create an express 4.9.5 system, just to test the tool, this is the current full command that works best for me:

NODE_PATH=/usr/lib/node_modules/:/usr/lib/node_modules/npm/node_modules:/usr/lib/node_modules/npm/node_modules/request/node_modules/form-data/node_modules baserock-import npm express 4.9.5 --use-local-sources --definitions-dir=./baserock/baserock/definitions --lorries-dir=./lorries/open-source-lorries --log=./import.log --use-master-if-no-tag

So to use the tool, cd to the directory that contains baserock/baserock, then run that command (exchanging 'express 4.9.5' for whatever package and version you want). This should build the desired stratum!

So, if you don't need to fully understand the tool, you may find it easier to just copy the above command. It's generally not a good idea to '--use master if no tag' if you can avoid it, but it's faster than hunting through untagged repos for the relevant tags if you're just testing that the tool works and you can use it. For more on tagging refs, see the troubleshooting page.

4) Describing your system

You'll then need to add the name of the stratum you just created to the web system stratum (or whatever system you're using) manually; again, see the import tool quickstart tutorial for more info. For the express system above, you would add:

- name: express
  morph: strata/express.morph

This has been tested in baserock; I was able to generate working systems containing various npm packages (some with many dependencies, some with none). I suggest testing the tool the first time using the exact command above, to create a system running express v4.9.5. You can then test it on your new system.

5) Very important notes

  • By default, your node_modules will be in usr/lib/node_modules. :)

  • If anything goes wrong, please check for the error on the import tool troubleshooting page.

Thanks for reading this tutorial, I hope it more or less made sense and I hope that you find it nicer to use than working through all of the dependencies you need by hand! Please send any feedback to the mailing list, or #baserock on irc.freenode.net.

(Zara wrote most of this tutorial, except for the lines copied verbatim from Sam's rubygems tutorial. Sam and Zara wrote most of the npm import tool itself.)