2b8834e92e
This fixes the bug where commands like `meteor add-platform ios` would
fail the first time with an error that cordova-lib could not be found,
even though we attempt to install the necessary packages if they have not
already been installed.
To make a very long story short, calling moduleDoesResolve before
installing dependencies like cordova-lib was causing Node.js to cache the
_absence_ of cordova-lib/package.json permanently in the new
packageJsonCache, which cannot be invalidated or cleared by user code:
f8f20892e9/lib/internal/modules/cjs/loader.js (L245-L255)
Although we could potentially propose a change to Node to allow the
packageJsonCache to be invalidated, a more immediate solution is simply to
avoid calling moduleDoesResolve when there's any chance the module will
not resolve. Because we still want to avoid repeatedly installing Cordova
dependencies every time we run a Cordova command, we instead check whether
the necessary dependencies are installed by examining the file system.
CLI
Files in this folder define the common framework for defining and parsing CLI
commands, options and properties such as inApp or inPackage.
It is encouraged to split out theme sharing commands into separate files.
An example of a command:
main.registerCommand({
name: 'some-command',
requiresRelease: false,
requiresApp: true,
// requiresPackage: true,
// requiresAppOrPackage: true,
pretty: true, // optional
minArgs: 1, // optional
maxArgs: 10, // optional
options: {
'long-option': { type: Boolean, short: 's', default: true, required: true },
'with-string': { type: String, short: 'w' }
}
}, function (options) {
var {appDir, packageDir, args} = options;
var longOption = options['long-option'];
var withString = options['with-string'];
...
});
This command will handle the following examples:
meteor some-command --long-option
meteor some-command -s
meteor some-command -s --with-string "some value"
meteor some-command -s -w "some value"
Note: don't pick a short key for an option unless it is very common to use it. The commands parser makes sure the same short key for an option is used consistently for the same kind of option across all commands. So two commands A and B can share a short option "c" only if it stands for the same long option in both cases.
Catalog refresh policy
You might notice that some commands are marked to never refresh the catalog. This is useful to make the command fast, if the command doesn't involve any network communication to the package server, it might be a good idea to forbid the preemtive refresh:
main.registerCommand({
...
catalogRefresh: new catalog.Refresh.Never()
});
Command return code
For some reason there are two ways to terminate the command with a non-standard exit code (non-zero, unix process exit code).
First way is just the return value of the command function, which should be a number.
The second way is to throw a special kind of exception:
main.registerCommand({...}, function (options) {
throw new main.ExitWithCode(2);
})
In case of additional options check, you can throw another special exception to show the help text for the command:
main.registerCommand({...}, function (options) {
if (options.bla === 'bad-value')
throw new main.ShowUsage;
})
There is also main.WaitForExit used for terminating after the subprocesses are
done. (XXX more info)
help.txt
The help.txt file contains all the information printed to the user when the
meteor help command is run. It has its own syntax where every command is
separated by a marker >>> with the name of the command.
Commands are parsed so the help text for an individual command could be separated from the rest.
Sadly, these commands need to be redocumented in the docs app as well. The docs text is not shared between these two places, yet.
Admin commands
Given that self-test is the only reliable way to test code in Meteor Tool, you
might need to create special "admin" commands. Since "admin" commands don't show
up in the help text, this namespace is abused to store all sorts of one-of
commands to run in automated and manual tests.