Create and deploy a server extension

A server extension is responsible for parsing and using any data the user enters in response to the global GlobalConfigFields and the instance InstanceConfigFields functions. See Class Helix.Core.Server.

A server extension is loaded into the P4 Server memory when an event occurs that launches that server extension. For example, when a client submits a file to the server's depot. The server extension persists in server memory for the lifetime of that client's connection to the server.

Extensions are run after triggers. If an extension fails for a specified event, subsequent extensions also associated with that event do not run.

Create

  1. On the client, run p4 extension --sample extName to create a skeleton of a server extension under the extName directory.
  2. Edit the placeholder data in the extName/manifest.json file. (See Server Extension JSON manifest fields.)
  3. Code the server extension by editing extName/main.lua to put in the logic.

    To learn more, see the README in the Extensions repository. See also the examples from a specific release, such as 2019.1.

  4. Run p4 extension --package extName to create extName.p4-extension.

Test

Test that the server extension does what you expect, make changes if necessary, and retest until the server extension is ready for production. See also Server extension errors and troubleshooting.

Deploy

  1. Install the server extension with p4 extension --install extName.p4-extension --yes.

    To run the install or delete of an extension, you must use the --yes option. Without --yes, the p4 extension command reports what it will do when the --yes is included.

  2. Configure the server extension:
    1. Configure the global settings with
      p4 extension --configure namespace::extName
    2. Configure the instance settings with
      p4 extension --configure namespace::extName --name namespace::extCfg.
      Deploying an extension requires the configuration of one or more instance specs. To learn how to create an instance spec, see Server extension configuration (global and instance specs).

About versions and code lines

  • Multiple versions of a server extension can be installed. For example, you might keep the first version in your bug-fix branch and install a different version in your new-feature branch.
  • Multiple versions of a server extension can be running simultaneously. For example, Release1.0-fileSizeCheck might be running in //depot/main while Release1.1-fileSizeCheck is running in //depot/dev.

About the data directory

  • Each version of a server extension can have a different data directory.
  • For a given version of a server extension, the data directory is shared between all instances. Consider whether concurrent access to data could affect your server extensions. For example, you might need a write lock on a log file.
  • A server extension’s data directory is not replicated.

Other examples

See the Extensions repository for server extension examples.