Extension basics
Signed extension
A signed extension assures a third party that the extension package and its code has not been altered. Signing your extension is optional. For a walkthrough of the signing process, see Creating and Installing Helix Core Signed Extensions in the Perforce Knowledge Base.
Installation
When you run p4 extension --install, the server extension is transferred from your client machine to the Helix Core Server, where built-in validation occurs. For example, the server notifies you if the manifest is missing or is invalid.
The server stores the server extension in a depot:
-
with the default name of .p4-extensions - see p4 extension in Helix Core Command-Line (P4) Reference,
-
that is of Type extension - see p4 depot for Form Fields > Type: > extension.
The server extensions depot is a new depot type because the files associated with a server extension are separate from the files in other types of Helix Core depots.
Viewing the history of extensions
A super user can run p4 changes on the extension depot to see the history of installs, upgrades, and deletes.
Listing extensions
See p4 extension in Helix Core Command-Line (P4) Reference, which explains the --list option.
Disabling and re-enabling an extension
To disable or re-enable a server extension, in the global configuration or in the instance configuration, change the value of ExtEnabled. See Fields that can be modified.
Deleting an extension
To delete a server extension, use p4 extension --delete extName --yes
To actually perform the install or delete of an extension, the --yes option is required. Without --yes, the p4 extension command merely reports what it would do without actually performing the install or delete.
This deletes the depot file and removes the server extension’s resource directory.
Directories
When a server extension is committed to the extensions depot, the server creates a subdirectory for the server extension. This directory is specified by the server.extensions.dir configurable. By default, the name of this directory matches the configurable's name, server.extensions.dir, and is located under the P4ROOT directory. Each server extension gets two subdirectories under the directory specified at server.extensions.dir:
| Subdirectory | Description |
|---|---|
server.extensions.dir/extension-key/1-arch
|
Resources for the extension. The |
server.extensions.dir/extension-key/1-data
|
A persistent scratch space that is not replicated. Also the location of the log. See Diagnostics / debugging. |
See also:
Prerequisite
Knowledge of Lua.
Limitation
Any plain-Lua library is compatible, provided that it matches version of the server extension runtime. However, external Lua libraries that require native machine code for a specific processor are not compatible.
Replication supported, but not DVCS
Server extensions are stored as normal depot files and use the existing file replication mechanism for transfer to replicas. Replicas install extensions as soon they received them from the commit server.
However, if your server extension has files that are stored in the server.extension.dir directory, those files will not be replicated.
DVCS instances do not receive server extensions.
Backup of server extensions
A backup of server extension archives is included if you make a backup of everything under P4ROOT that includes hidden files and directories. By default, the extension archives are in a hidden depot named .p4-extension under P4ROOT. The path to the extensions directory is available to a user with the super access level. See p4 depots in Helix Core Command-Line (P4) Reference.
The server.extensions.dir configurable points to the uncompressed extension archives and any content that they might have created. Depending on the extension, the content that the extension creates might be worth backing up.
If the uncompressed extension archives under the server.extensions.dir are not present, the server recreates them from the source archives in the Extension depot.
Server extension specs are included in checkpoints.
Internationalization
The server extensions API and manifest allow extensions to return messages localized by locale to the user. Message strings are encoded as UTF-8 and can be converted to other character sets. See the For details, see the Internationalization Notes.
Diagnostics / debugging
To log line-delimited JSON from within a server extension, use the Helix.Core.Server.log() function. See Class Helix.Core.Server.
Documentation from the command-line
See p4 help serverextensionintro