Server extension creation

Workflow to create and deploy a server extension

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.

    See the information about examples at https://swarm.workshop.perforce.com/files/guest/perforce_software/extensions/main/README.md
    and the examples at a specific release, such as https://swarm.workshop.perforce.com/files/guest/perforce_software/extensions/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 perform the install or delete of an extension, the --yes option is required. 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 want to 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.
  • The 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.

Other examples

See the server extension examples at https://swarm.workshop.perforce.com/files/guest/perforce_software/extensions