JSPM

The xPack package manager command line tool

A Node.js CLI application to manage xPacks.

xPacks overview

xPacks are general purpose software C/C++ packages, intended to enhance code sharing and reusing during the development of C/C++ libraries and applications, much the same as npm modules do so nicely in the JavaScript ecosystem.

Purpose

The main purpose of the xpm tool is to install xPacks, including all dependent xPacks, and to easily update them when new versions are released.

For developers, xpm provides a very convenient way of publishing the software packages, using the same central repository as npm.

Prerequisites

If this is your first encounter with npm, you need to install the node.js JavaScript run-time. The process is straightforward and does not pollute the system locations significantly; there are two node versions, LTS (Long Term Service) and Current; generally it is safer to use LTS, especially on Windows. Download the package suitable for your platform and install it as usual. The result is a binary program called node that can be used to execute JavaScript code from the terminal, and a link called npm, pointing to the npm-cli.js script, which is part of the node module that implements the npm functionality.

Although not mandatory for xpm, on Windows, it is recommended to also install the Git for Windows package.

Easy install

The command line module is available as xpm from the public repository; with npm already available, installing xpm is quite easy.

macOS and GNU/Linux

Since xpm behaves like a system wide command, it is recommended to install it globally:

$ sudo npm install xpm --global

The result is a link in /usr/local/bin:

$ ls -l /usr/local/bin/xpm
lrwxr-xr-x  1 root  wheel  34 Nov 13 03:02 /usr/local/bin/xpm -> ../lib/node_modules/xpm/bin/xpm.js

To test if xpm starts:

$ xpm --version
0.3.3

To remove xpm, the command is similar:

$ sudo npm uninstall xpm --global

Windows

On Windows, global packages are installed in the user home folder (like C:\Users\ilg\AppData\Roaming\npm), and do not require sudo.

C:\>npm install xpm --global

The result is a pair of files in the %APPDATA%\npm folder:

C:\>dir "%APPDATA%"\npm\xpm*
 Volume in drive C has no label.
 Volume Serial Number is 28CE-1C06

 Directory of C:\Users\Liviu Ionescu\AppData\Roaming\npm

18/04/2018  10:40               319 xpm
18/04/2018  10:40               196 xpm.cmd
               2 File(s)            515 bytes
               0 Dir(s)  51,207,155,712 bytes free

However, attempts to start the program fail:

C:\>xpm --version
'xpm' is not recognized as an internal or external command,
operable program or batch file.

The reason is that this path is not in the default environment, and must be added manually.

C:\>setx Path "%Path%;%APPDATA%\npm"

After this, the program should start normally:

C:\>xpm --version
0.3.3

To remove xpm, the command is similar:

C:\>npm uninstall xpm --global

npm folders

For more details on the folders used by npm, see npm-folders.

xpm folders

To avoid security issues and the need to increase the user privilege level, xpm does not use any system folders, and all activity happens in the user home location.

There are two main folders:

• a cache folder, where all downloaded files are stored
• a central repository folder, where the xPacks are expanded

For more details see xpm folders.

macOS specifics

On macOS, the central repository is located in ~/Library/xPacks. By default, ~/Library is hidden and does not show in folder selections.

To make it visible, use:

$ /usr/bin/chflags nohidden ~/Library
$ xattr -d com.apple.FinderInfo ~/Library

User info

To get an initial glimpse on the program, ask for help:

$ xpm --help

The xPack package manager command line tool
Usage: xpm <command> [<subcommand>...] [<options> ...] [<args>...]

where <command> is one of:
  build, init, install, run-script

Common options:
  --loglevel <level>     Set log level (silent|warn|info|verbose|debug|trace) 
  -s|--silent            Disable all messages (--loglevel silent) 
  -q|--quiet             Mostly quiet, warnings and errors (--loglevel warn) 
  --informative          Informative (--loglevel info) 
  -v|--verbose           Verbose (--loglevel verbose) 
  -d|--debug             Debug messages (--loglevel debug) 
  -dd|--trace            Trace messages (--loglevel trace, -d -d) 
  -C <folder>            Set current folder 

xpm -h|--help            Quick help 
xpm <command> -h|--help  Quick help on command 
xpm --version            Show version 
xpm -i|--interactive     Enter interactive mode 

npm xpm@0.2.10 '/Users/ilg/My Files/MacBookPro Projects/xPack/npm-modules/xpm-js.git'
Home page: <https://github.com/xpack/xpm-js>
Bug reports: <https://github.com/xpack/xpm-js/issues>
$

Developer info

Git repo

$ git clone https://github.com/xpack/xpm-js.git xpm-js.git
$ cd xpm-js.git
$ npm install
$ sudo npm link 
$ ls -l /usr/local/lib/node_modules/

A link to the development folder should be present in the system node_modules folder, and also a link to the xpm executable should be available system wide.

Tests

The tests use the node-tap framework (A Test-Anything-Protocol library for Node.js, written by Isaac Schlueter).

As for any npm package, the standard way to run the project tests is via npm test:

$ cd xpm-js.git
$ npm install
$ npm test

A typical test result looks like:

$ npm run test
...

To run a specific test with more verbose output, use npm run tap:

$ npm run tap test/tap/...

Coverage tests

Coverage tests are a good indication on how much of the source files is exercised by the tests. Ideally all source files should be covered 100%, for all 4 criteria (statements, branches, functions, lines).

To run the coverage tests, use npm run test-coverage:

$ npm run test-coverage
...

Continuous Integration (CI)

The continuous integration tests are performed via Travis CI (for POSIX) and AppVeyor (for Windows).

Standard compliance

The module uses ECMAScript 6 class definitions.

As style, it uses the JavaScript Standard Style, automatically checked at each commit via Travis CI.

Known and accepted exceptions:

• none.

To manually fix compliance with the style guide (where possible):

$ npm run fix

> xpm@0.1.10 fix /Users/ilg/My Files/MacBookPro Projects/xPack/npm-modules/xpm-js.git
> standard --fix

Documentation metadata

The documentation metadata follows the JSdoc tags.

To enforce checking at file level, add the following comments right after the use strict:

'use strict'
/* eslint valid-jsdoc: "error" */
/* eslint max-len: [ "error", 80, { "ignoreUrls": true } ] */

Note: be sure C style comments are used, C++ styles are not parsed by ESLint.

Maintainer info

How to publish

To check the last commits:

$ git log --pretty='%cd * %h %s' --date=short

• commit all changes
• npm run test (fix included)
• update CHANGELOG.md; commit with a message like CHANGELOG: prepare v0.1.2
• npm version patch
• push all changes to GitHub; this should trigger CI
• wait for CI tests to complete
• npm publish

License

The original content is released under the MIT License, with all rights reserved to Liviu Ionescu.

The design is heavily influenced by the npm application, Copyright (c) npm, Inc. and Contributors, Licensed on the terms of The Artistic License 2.0.

Note

The xpm tool is currently experimental and should not be used in production environments.