P4 Templates

Overview

This P4 Project Template Tool can be used to quickly setup and create a p4 environment for a new Perforce Helix Core project. Use this set of Python scripts to deploy a standard setup or build upon this script to create a customized template. This package also includes demo templates for Unreal Engine and Unity.

• Who Is the P4 Project Template Tool for?

  • Admins of studios that want to predefine a project structure standard and deploy that structure repeatedly.

• What Does the P4 Project Template Do?

  • Allows admin users to pre-define and deploy project templates which can create and connect new objects and definitions in your Helix Core server.

    • Users can create and define the following types of objects: depots, streams, user groups permission table entries, typemap table entries, and branches that can be used to prepopulate a new depot from an existing depot in your Helix Core server.

• How to Use P4 Project Templates

  • Once defined, users can easily reuse individual project style templates with variable definitions when creating and deploying similar future projects.

  • At any point a project template may be redefined and saved in place or as a new file if your project needs change.

See this video for how to setup and use here >> https://youtu.be/lxwCVbOLdag

Installation

Currently, the running the main kernel via source doesn't require any additional libraries beyond Python3 The UI currently requires PyQt6.

Requirements

CLI:

p4python 2023.2.2581979\

GUI:

PyQt6 6.6.1

EXE BUILD Requirements:

altgraph 0.17.4
packaging 24.0
pefile 2023.2.7
pyinstaller 6.5.0
pyinstaller-hooks-contrib 2024.3
pywin32-ctypes 0.2.2
setuptools 69.2.0

Testing requirements:

colorama 0.4.6
coverage 7.4.4
iniconfig 2.0.0
pluggy 1.4.0
pytest 8.1.1
pytest-cov 5.0.0
pytest-mock 3.14.0

Server Configuration File

• Server configuration is taken from the config.json that can either be positioned next to the exe file or passed in as a command line argument when calling the tool.

{
    "server":{
        "port": "ssl:helix_core_server:1666",
        "user": "username",
        "password": null,
        "charset": "none"
    },
    "template_dir": ""
}

Template Directory

• The template directory can either live next to the exe file, be defined within the exe file, or passed in as a command line argument.

Templates

• If you're looking to define new templates by hand, the template structure can be viewed in the example templates. Alternatively you can use the template Editor UI to author new templates with the proper formatting in place.

CLI Usage

• To process a specific json template pass in the file path with the -t flag. You can find example templates in the p4templates/templates directory. Copy one if these templates, edit to fit your needs, and then process it to add the requested components to your p4d server. To Note: You will need the p4 Permissions level required to complete these actions for the script to succeed.

python ./kernel/process_template.py -t /path/to/template/file.json

• If you have a specific template predefined you can use the -n --name option that corresponds to either the name field as defined in the template file, or the filename itself.

python ./kernel/process_template.py -n template_name

• If you are using parameter tags in your template you can use the -p,--parameter flag to input these values for processing. The syntax is as follows with a ':' acting a string delimiter between the key and value. Any number of parameters may be passed in separated by a space. For instance if your template uses the parameters 'project' and 'dept' you would use the following syntax to pass the substitutions into the cli utility. Within your json file the syntax for parameters is to use curly braces to identify parameter values. For example a template json string of: {"streams": [{"depot": "{dept}_depot", "name": "{project}_{dept}_main"}]} would result in the creation of mainline stream named demo_3D_main within the 3D_depot depot.

python ./kernel/process_template -n default_unreal_template -p project:demo dept:3D

• the -d,--dryrun flag can be used to preview the the template output with the parameter substitutions applied. The output will be printed to the command line instead of being processed by the server.

python ./kernel/process_template -n default_unreal_template -p project:demo dept:3D -d

File Population

The template system utilizes Helix Core's branch mappings and the p4 populate command to duplicate files and folders from one depot position on the server into the new template project. For this to operate correctly I recommend you establish a separate template project depot on your p4d server and then use those boilerplate setups as your duplication source.

For example, in the following snippet we see the branch mapping section from a p4 setup template showing how the view section is defined for file propagation including file renaming.

  "branches": [
    {
      "name": "{project}_populate",
      "options": [
        "unlocked"
      ],
      "view": {
        "//populate_demo/main/old_project/...": "//{project}_depot/{project}_main/new_project/...",
        "//populate_demo/main/old_project/old_project.py": "//{project}_depot/{project}_main/new_project/new_project.py"
      }
    }
  ],

GUI Usage

• To load the editor GUI use the launch the exe. By default the exe will look for a config file and template directory next to the executable itself, however these values can be passed in as command line arguments as well. The template directory can also be defined in the config file itself.

E:\repos\p4templates\bin>E:\repos\p4templates\bin\p4_template.exe -h
usage: p4_template.exe [-h] [-c CONFIG] [-t TEMPLATE_DIR]

options:
  -h, --help            show this help message and exit
  -c CONFIG, --config CONFIG
  -t TEMPLATE_DIR, --template_dir TEMPLATE_DIR

python ./p4_template_tool.py

• Upon loading the UI you will be presented with the template loader execution window. Any variable parameter will be lifted and shown in the field below the template selection drop down. Once all parameters have a valid value then you will be able to process the template. If you would like to edit a current template the Edit button will open the Edit Template window with the data for the currently selected template. This can then be either saved as the same file name or as a new name to create a copy. If you would like to create a new template, the New button will open the Edit Template window without any predefined values.

EXE Build

• If you have the pyinstaller requirements installed. build_windows.bat will create a self contained executable in the bin directory.

Testing

• run_tests.bat should take care of things so long as you have the testing requirements installed. Currently basic unit tests are in place. If you update the code at all be sure to update the tests accordingly. Test results will be available via command line and coverage reports can be viewed via the html-cov/index.html file that will be generated by coverage.
• This script will attempt to upload test results to coveralls, however don't be concerned if this portion fails as it does require a private repo_token that will not be included in this github repository.

TODO Wishlist

• Documentation
  • More than a readme and video walkthrough is likely needed.
• Validation
  • I would prefer if this tool could validate the entries per tab, and particularly on the type map to stop and erroneous edits.
• Cleaner CLI
  • entry point other than kernel\process_template.py?
  • A separate entry point should be stabilized beyond reaching into the kernel directly.