How to install xcdl
Prerequisites
For first-time Node.js users, it is highly recommended to read the instructions on the xPack Prerequisites page.
Quick instructions
For those who have already performed the install steps on the xPack Prerequisites page and are familiar with the process, here are the commands you need. Simply copy and paste them into your terminal (hover the mouse over the command, and a copy button will appear on the right side; click it to copy the command).
- Windows
- macOS
- GNU/Linux
Download the Windows Prebuilt Installer (a node-v*-x64.msi file) from the
Download Node.js
page and install it as usual, with administrative rights.
Avoid selecting the Tools for Native Modules during installation.
Although not mandatory, it is recommended to update npm to the latest version:
npm install -location=global npm@latest
Update the user Path and make it persistent:
set Path=%APPDATA%\npm;%Path%
setx Path "%APPDATA%\npm;%Path%"
Configure PowerShell to allow the execution of node.js applications:
Set-ExecutionPolicy -ExecutionPolicy Bypass -Scope CurrentUser
To install node via the nvm version manager, run the following script through your shell:
curl https://raw.githubusercontent.com/xpack/assets/master/scripts/install-nvm-node-npm-xpm.sh | ${SHELL}
export NVM_DIR="$HOME/.nvm"
source "$NVM_DIR/nvm.sh"
This script, in addition to installing node and npm, also installs xpm.
To install node via the nvm version manager, run the following script through your shell:
wget -q -O - https://raw.githubusercontent.com/xpack/assets/master/scripts/install-nvm-node-npm-xpm.sh | ${SHELL}
export NVM_DIR="$HOME/.nvm"
source "$NVM_DIR/nvm.sh"
This script, in addition to installing node and npm, also installs xpm.
Install
With the environment properly set, the command to install xcdl is:
npm install --location=global xcdl@latest
This command installs the latest available version.
To install a specific version, mention it explicitly:
npm install --location=global xcdl@2.0.0
- Windows
- macOS
- GNU/Linux
On Windows, global Node.js 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.
The result of installing xcdl is a set of files in the %APPDATA%\npm folder:
C:\>dir "%APPDATA%"\npm\xcdl*
Volume in drive C has no label.
Volume Serial Number is B02D-925C
Directory of C:\Users\ilg\AppData\Roaming\npm
29/07/2024 07:24 397 xcdl
29/07/2024 07:24 329 xcdl.cmd
29/07/2024 07:24 821 xcdl.ps1
3 File(s) 1,547 bytes
0 Dir(s) 39,088,439,296 bytes free
If you followed the instructions in the prerequisites section, you should already have this path configured and the program should start normally:
C:>xcdl --version
2.0.0
On macOS, if you ran the install-nvm-node-npm-xpm.sh scripts described
in the previous section, you should
already have npm correctly configured to use a location in the home folder.
% which xcdl
/Users/ilg/.nvm/versions/node/18.20.4/bin/xcdl
To test if xcdl starts:
% xcdl --version
2.0.0
Show macOS hidden files
The default location used to install the global packages is
below ~/Library, a folder that, due to an unfortunate Apple decision,
is hidden for regular browsing in Finder.
To make it back visible, use:
/usr/bin/chflags nohidden ~/Library
xattr -d com.apple.FinderInfo ~/Library
A more general solution is to make all hidden files visible:
defaults write com.apple.Finder AppleShowAllFiles true
killall Finder
Another annoying behaviour of the file browser is to hide names starting
with . (dot), which is a real pity since the binary packages are
extracted in a folder named .content.
Fortunately there is a workaround for this too:
cmd+shift+'.'
This keyboard shortcut works like a toggle, using it once makes files starting with dot visible, using it again reverts to hiding them.
On GNU/Linux, by default, when using system packages,
global Node.js packages are installed in
/usr/local, and managing them requires administrative rights,
but if you ran the install-nvm-node-npm-xpm.sh scripts described
in the previous section, you should
already have npm correctly configured to use a location in the home folder.
To test if xcdl starts:
$ which xcdl
/home/ilg/.nvm/versions/node/18.20.4/bin/xcdl
$ xcdl --version
2.0.0
Uninstall
The command to remove xcdl is:
npm uninstall --location=global xcdl
Do not install npm with administrative rights!
Installing npm with administrative rights is strongly discouraged, as it leads to installing all other CLI programs (including xpm) with administrative rights as well. Instead, use a node version manager.
For completeness, the official page explaining how to install npm in a custom folder is Resolving EACCES permissions errors when installing packages globally.
npx
If, for any reason, you decide not to install xcdl, you can still
benefit from it by using the npx command, as a trampoline to start xcdl:
$ npx xcdl --version
2.0.0
However, for regular usage, this method is not efficient, since npx will need to prepare the Node.js module for each run, and this takes some time.
npm folders
For more details on the folders used by npm, see npm-folders.
Quick info
To get an initial overview of the program, request help by using the following command:
% xcdl --help
The xPack components manager command line tool
Usage: xcdl <command> [<subcommand>...] [<options> ...] [<args>...]
where <command> is one of:
setup, build, test
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)
--no-update-notifier Skip check for a more recent version
-C <folder> Set current folder
xcdl -h|--help Quick help
xcdl <command> -h|--help Quick help on command
xcdl --version Show version
xcdl -i|--interactive Enter interactive mode
npm xcdl@2.0.0 '/Users/ilg/.nvm/versions/node/undefined/lib/node_modules/xcdl'
Home page: <https://xpack.github.io/xcdl/>
Bug reports: <https://github.com/xpack/xcdl-js/issues/>
%