dev install

Point the application's installed executable at a checkout

Command version
0.0.0
Command configuration
cli:cli.install@0.0.0

Arguments

ArgumentTypeRequiredDefaultDescription
--pathpathNo"."Checkout to install the application from (default: current directory): a tree holding its repository, the distribution itself, or the package directory inside it. Whatever is checked out there is what the executable will read
--tool-rootpathNoDirectory the tool environment and its entry point are placed under, for an install that must not replace the one on PATH; without it the machine's own tool root is used
--force,
--no-force
booleanNofalseRebuild the tool environment even when the install already reads this checkout and boots -- what a dependency change needs, and what a source change does not, since an editable install reads the checkout itself

It also takes the global arguments.

Output

It answers with a install.installSummary.

Examples

dev install

Point the installed executable at the checkout in the current directory.

dev install --path ../workspace --tool-root ../tools

Install from another checkout into a tool root of its own, leaving the one on PATH alone.

Errors

CodeMeaningRemedy
TARGET_PATH_NOT_DIRECTORYThe path --path names is not a directory.Name the checkout to install from, a tree holding it, or the package directory inside it.
NO_PACKAGE_TO_INSTALLThe directory --path names holds no distribution of this application's package to install from.Point --path at a checkout of the repository the application is developed in, at a tree holding that checkout, or at the package directory inside it.
INSTALL_FAILEDThe package manager failed to install the application from the checkout; the message carries its output.Repair what the output names -- most often a dependency the checkout cannot obtain -- and run install again.
TOOL_ENVIRONMENT_IN_USEAnother running process holds the environment the application is installed in, so it could not be replaced.Wait for that process to finish and run install again, or install by hand with the command the message gives.
CHECKOUT_DOES_NOT_STARTThe application, run from the checkout before anything was replaced, does not start, so the install was left as it was.Obtain what the checkout depends on -- vendor its libraries, sync its environment -- and run install again.
CANNOT_REPLACE_THIS_ENVIRONMENTThe command is running from inside the environment it would replace, which cannot be replaced from within.Run it from another environment -- the checkout's own, with the application started as a module -- or install by hand with the command the message gives.
EXECUTABLE_DOES_NOT_BOOTThe application was installed from the checkout, but its executable does not start afterwards, even after a retry without the package cache.Install it by hand with the command the message gives, and read what the executable prints when started.
Also every code of cli:cli
CodeMeaningRemedy
REPO_ROOT_VALIDATION_FAILEDThe repository root the run was given, by --repo-root or by the directory it was started in, is not a directory that can be acted on.Run the command from inside the repository, or pass --repo-root naming its root.
RUNTIME_CONFIG_FAILEDA runtime configuration file the run reads -- the application's cli.config.yml at one of its scopes -- does not load, or sets an argument default a scope may not set.Correct the file the message names; config init writes one that loads.
COMMAND_CONFIG_FAILEDThe configuration the command itself is declared by does not load, so the command cannot be run. This is a fault in the application as it was built, not in anything the person running it supplied.Report it against the application's release, with the message; reinstalling the release with update --force replaces a damaged copy.
MANIFEST_VALIDATION_FAILEDThe command reads the repository's manifest.yml, and none was found at the root, or the one found does not load.Run the command in a repository that has a manifest, pass --manifest naming one, or correct the manifest where the message says it does not load.
APP_CONFIG_FAILEDThe application's own configuration file in the repository does not load against the type the application declares for it.Correct the file the message names; config init writes one that loads.
INPUT_VALIDATION_FAILEDAn argument the command line gave is not one the command accepts once it is read -- the wrong type, a value outside its choices, or one a rule on the input refuses.Give the argument as the command's --help describes it.
OUTPUT_VALIDATION_FAILEDThe command answered with data that does not match the output it declares, so the answer was withheld. This is a fault in the command, not in how it was run.Report it against the application's release, with the command line that produced it.
PIPE_STDIN_NOT_PIPEDThe command was asked to take its input from stdin, by --from-stdin or by - as a document input's value, and nothing is piped to it -- stdin is a terminal, or there is none.Pipe in the output of a command run with --response-format json, or give the input another value.
SECRET_NOT_GIVENThe command takes a secret input, which is never typed on the command line, and nothing was typed at its prompt or piped to its standard input.Run the command at a terminal and type the value at the prompt, or pipe it to the command's standard input, one line for each secret it takes.
SECRET_STDIN_CLAIMEDThe command takes a secret input from standard input, and standard input already carries its piped inputs -- --from-stdin, or a document input given - -- so there is nothing to read the secret from.Run the command at a terminal to be asked for the secret, or give its other inputs on the command line.
PIPE_STDIN_CLAIMED_TWICE--from-stdin was given beside a document input given - or -:<path>, so the piped answer would be both the command's inputs and one of them.Keep one of the two forms.
PIPE_FIELD_NOT_FOUNDA document input given -:<path> names a field the piped answer does not hold -- a key no mapping on the way has, or an index past the end of a list or into something that is no list -- or the text after -: is no path.Name a field the command before the pipe answers with, as keys joined by . with [<n>] picking an item from a list, as releases[0].notes.
ENVELOPE_UNREADABLEWhat was piped to the command is not an envelope a command writes, so there is no answer in it to take as input.Run the command before the pipe with --response-format json, and pipe nothing else between the two.
PIPE_UPSTREAM_FAILEDThe command before the pipe refused, so there is no answer to take as input and this command did not run. Its own errors follow this one in the envelope.Repair what the errors after this one name, in the command before the pipe, and run the pipeline again.
PIPE_ANSWER_NOT_INPUTS--from-stdin takes the piped answer as the command's inputs by name, and the answer is no mapping, or carries a field the command declares no input for.Pipe in a command whose answer holds only this command's inputs, or give the answer to one document input with - instead.
UNHANDLED_EXCEPTIONThe command failed in a way nothing anticipated, and the message is the failure's own text.Report it against the application's release, with the command line and the message.
APPLICATION_RELEASE_NAME_UNKNOWNThe application could not tell which release it is -- the project it was released with, or which of that project's applications it is -- so it cannot look its releases up.Run the application as it was installed, from the directory toolchain install placed it in, or report it against the release.

Exit codes

CodeMeaning
0The command answered; the envelope's status is success and errors is empty.
1The command or the framework refused; the envelope's status is error and errors names each code, with its message.
2The command line could not be read -- an unknown command, a missing or unknown argument -- so nothing ran and no envelope was written; the usage is printed instead.

Types

install.installSummary

FieldTypeRequiredDefaultDescription
projectDirstringNo""The distribution the executable was pointed at
toolRootstringNo""The tools directory the install was made under, empty for the machine's own
reinstalledbooleanNofalseWhether the tool environment was rebuilt
alreadyCurrentbooleanNofalseWhether the install already read this distribution and booted, so nothing was rebuilt
retriedWithoutCachebooleanNofalseWhether the first install would not start and was made again with the installer's cache bypassed
blockedstringNo""Why the install was not re-pointed although it needed to be
blockedByAnotherProcessbooleanNofalseWhether the refusal is another process holding the environment, rather than this process running from it
installedAtstringNo""The directory the install reads, as it stood when this finished
executablestringNo""The installed executable
executableOkbooleanNofalseWhether the installed executable starts