Features

Installing a package makes its files available. A feature performs additional setup, such as defining a service or changing a setting, through scripts you explicitly run. Installing its package does not run those scripts or turn the feature on. Package-manager maintenance steps are a separate, closed set, not feature scripts.

Start with feat list and feat info <name> to see what is available, its state and what it says it will change. Use Using feat for the commands, or open Feature Manager from the launcher by typing feature.

What a feature can do #

A feature's scripts run as whoever asked, with no authority of their own. feat grants nothing: a script can do exactly what the person running it could do by hand. An Administrator's request can define a service; the same request from someone else is refused by the system, at whatever step needs the authority.

Its lifecycle #

A feature is in one of three settled states, and moves between them a step at a time:

Turning on a feature that isn't installed installs it first. Removing one that is on turns it off first. Each step runs one script: install.sh, enable.sh, disable.sh or uninstall.sh. A feature that has nothing to do at a step ships no script for it, and the step only records the new state.

What a feature's own words say about when it takes effect matters: dynamic boot's services, for example, start at the next boot after it is turned on.

Interrupted #

Before each step's script runs, the step is recorded as begun; once the script succeeds, the new state is recorded. A script that fails or is stopped therefore leaves the feature interrupted — installing, turning on, turning off or removing — rather than claiming a state it never reached.

An interrupted feature is fixed by asking again: running the same step reruns its script from the start, which every feature's scripts are written to allow. Or it can be taken the other way: an interrupted turn-on can be turned off, an interrupted install removed.

Where its state is kept #

Changing a feature requires write access to its registry state. As shipped, Administrators can change it and everyone can read it. Use feat or Feature Manager rather than editing numeric state to make a failed step look complete: the scripts' work may still be unfinished.

The client reference keeps the definition path, registry key and complete numeric state mapping.

When its package is removed #

Removing the package that brought a feature takes its scripts away, but not what they set up, since package removal does not run the feature's teardown scripts. The registry still holds the feature's state, and both feat list and Feature Manager show it as having no definition. Installing the package again brings the scripts back, so the feature can be turned off or removed properly.

Remove a feature before removing its package. Verify the feature's state with feat list or feat info <name> after the removal. If its definition is already missing, install the supplying package again, inspect the feature, then use feat remove <name> while the scripts are available. Package undo or recover is not a substitute for running the feature's teardown scripts.

Features in an image #

An image can install or turn on features as it is built, with [[feature]] in its spec. They are set up at the image's first boot, before its services start.

Where to go next #

• Using feat, the command.
• Feature Manager, the window.
• Writing a feature, to ship one with your own package.

feat runs a feature's scripts and records its state. It runs them as you: what you may change is what you could change by hand.

Inspect, change and check a feature #

Start by reading the feature's own description; it tells you what setup does and when it takes effect. For example:

feat list
feat info dynamic-boot
feat add dynamic-boot
feat info dynamic-boot

add installs and enables the feature. Use install instead if you want setup only, or enable when it is already installed. For dynamic-boot, the services start at the next boot; an enabled state does not mean they have already started. Read the script output as well as the final state. For the watchers, output destination and rebuild evidence, use the update-activation checks; enabled or running alone is not proof of boot readiness.

The scripts run with your rights. Permission to update the feature's state does not guarantee permission for every action its scripts attempt.

Turn off or remove setup #

feat disable <name>
feat info <name>

This leaves the feature installed but off. To remove what it set up:

feat remove <name>
feat info <name>

remove turns an enabled feature off first. It does not remove the package that supplies the scripts, so the feature remains available to set up again. Remove setup before removing its package with peipkg.

Recover an interrupted feature #

1. Read the failed script's output and inspect feat info <name> or feat list to identify the interrupted phase.
2. Address the reported cause, such as missing authority or a resource the script needs. Updating the recorded state alone does not finish the work.
3. Run the same command again to retry the step from the start. Feature scripts are required to tolerate that retry.
4. Inspect the result again. If you want to back out, an interrupted enable can be disabled, and an interrupted install can be removed.

An interruption is recorded rather than automatically rolled back as a package transaction. If the definition is missing, restore the supplying package first so the feature's scripts can perform the retry or teardown. See Interrupted and When its package is removed.

Commands #

Asking for what is already so does nothing and says so: feat enable on a feature that is on, feat disable on one that is off. Asking again after an interruption reruns the step's script (see Interrupted).

$ feat add dynamic-boot
applied 1 keys
applied 1 keys
dynamic-boot: created mkirf-watch and mkuki-watch (disabled)
feat: installed dynamic-boot
set Machine\System\Services\mkirf-watch Disabled = REG_DWORD 0   (layer: base)
set Machine\System\Services\mkuki-watch Disabled = REG_DWORD 0   (layer: base)
dynamic-boot: enabled mkirf-watch and mkuki-watch (start on next boot)
feat: enabled dynamic-boot
$ feat enable dynamic-boot
feat: dynamic-boot already enabled

The scripts' own output, and that of the commands they run, appears as they run, between the lines feat writes.

Exit codes #

For a program #

Human commands and their exit codes are above. Programs can query JSON or run a change in driven mode; the complete schemas and error codes are in the feat client reference.

--json #

feat list --json returns an array and feat info <name> --json an object. See query members and permission checks for state, defined, may_change and the other fields. Permission to write state says nothing about whether a script can complete its work.

--driven #

feat --driven <command> <name> emits JSON Lines for a change. It asks no questions and gives scripts empty standard input. See events and terminal outcomes. A client going away does not stop the change; inspect its eventual state. Use --json for list and info, which driven mode refuses.

Feature Manager is the desktop's window on features. Open it from the launcher (type feature). It has no authority of its own: it runs feat as you, so what you may change is exactly what you could with the command.

The cards #

Each feature on this machine is a card: its title and name, its state, and what it says it does. The state is one of:

A feature comes in a package: one installed with Package Manager appears here.

The buttons #

While a change is being made, its card shows which script is running and the last thing it said. Once it is done, the line along the bottom says so.

If a script fails, the card says which, shows everything the script said, and offers Try Again. The feature is left interrupted until it is tried again or taken the other way.

A change is made to the end even if you close the window: the window stays until then, saying so, and then closes.

What you may do #

Whether you may change a feature is asked of the system, by feat. As shipped, only Administrators may. Anyone else sees every feature and its state, with the reason said once at the top, and no buttons.

Being allowed to change a feature's state doesn't make every script able to do its work: a script that needs more than you have fails, and says so on the card.

Where to go next #

• Using feat, the same from a terminal, and for a program of your own.
• Writing a feature.