Neutralize Pesky Miscreants
Share your code. npm Orgs help your team discover, share, and reuse code. Create a free org »

xpm

0.4.5 • Public • Published

npm (scoped) license Standard Travis AppVeyor

The xPack package manager command line tool

xpm is a Node.js CLI application to manage xPacks.

xpm is an open source project, hosted as xpack/xpm-js on GitHub.

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

The official page explaining how to install npm in a custom folder is How to Prevent Permissions Errors

For advanced users, see the page Using a Version Manager to install Node.js and npm.

Easy install

The command line tool is implemented as a portable node module, available as xpm from the public repository.

Windows

On Windows, by default, global node packages are installed in the user home folder, in %APPDATA%\npm (like C:\Users\ilg\AppData\Roaming\npm), and managing packages does not require administrative rights.

C:\>npm install --global xpm

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 starts normally:

C:\>xpm --version
0.4.3

To remove xpm, the command is similar:

C:\>npm uninstall --global xpm

macOS

On macOS, by default, global node packages are installed in /usr/local, and managing them requires administrative rights.

$ sudo npm install --global xpm

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

However, the recommended install location is ${HOME}/Library/npm.

For those who already performed the install in /usr/local, the command to remove it is:

$ sudo npm uninstall --global xpm

The commands to set this custom location are:

$ mkdir -p "${HOME}"/Library/npm
$ npm config set prefix "${HOME}"/Library/npm
$ echo 'export PATH="${HOME}"/Library/npm/bin:${PATH}' >> "${HOME}"/.profile
$ source "${HOME}"/.profile

With the environment properly set, the command to install xpm is:

$ npm install --global xpm

To test if xpm starts:

$ xpm --version
0.4.3

To remove xpm, the command is similar:

$ npm uninstall --global xpm

GNU/Linux

On GNU/Linux, by default, global node packages are installed in /usr/local, and managing them requires administrative rights.

$ sudo npm install --global xpm

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

However, the recommended install location is ${HOME}/opt/npm.

For those who already performed the install in /usr/local, the command to remove it is:

$ sudo npm uninstall --global xpm

The commands to set this custom location are:

$ mkdir -p "${HOME}"/opt/npm
$ npm config set prefix "${HOME}"/opt/npm
$ echo 'export PATH="${HOME}"/opt/npm/bin:${PATH}' >> "${HOME}"/.profile
$ source "${HOME}"/.profile

(Thse commands were tested with bash, for other shells may need small adjustments).

With the environment properly set, the command to install xpm is:

$ npm install --global xpm

To test if xpm starts:

$ xpm --version
0.4.3

To remove xpm, the command is similar:

$ npm uninstall --global xpm

npx

If, for any reason, you decide not to install xpm, you can still benefit from it by using npx, as a trampoline to start xpm:

$ npx xpm --version
0.4.3

However, for regular usage, this method is not efficient, since npx will need some time to prepare the node module for each run, and this takes some time.

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 xPack 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

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

$ sudo npm link 
up to date in 4.992s
/usr/local/bin/xpm -> /usr/local/lib/node_modules/xpm/bin/xpm.js
/usr/local/lib/node_modules/xpm -> /Users/ilg/My Files/MacBookPro Projects/xPack/npm-modules/xpm-js.git

On Windows, or on machines where the install folder is in the user home, the command does not require sudo, for example on macOS:

$ npm link
up to date in 4.985s
/Users/ilg/Library/npm/bin/xpm -> /Users/ilg/Library/npm/lib/node_modules/xpm/bin/xpm.js
/Users/ilg/Library/npm/lib/node_modules/xpm -> /Users/ilg/My Files/MacBookPro Projects/xPack/npm-modules/xpm-js.git

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

install

npm i xpm

Downloadsweekly downloads

138

version

0.4.5

license

MIT

homepage

github.com

repository

Gitgithub

last publish

collaborators

  • avatar