Conductor User Guide¶
Conductor is PROS’s templating and project management facility. It is responsible for resolving versions of the PROS kernel and user libraries. It also provides information about a PROS project to other PROS facilities, like providing the target platform (e.g. V5 or Cortex) to the upload utility.
There are a few concepts central to Conductor’s functionality:
- Templates: Templates are a description of a set of files. They have a name, version, supported target, and possibly other metadata. Templates typically come in one of 3 forms: remote, local, and installed. A remote template is a template that can be downloaded. A local template is a downloaded template that can be installed to a project, even when you’re offline. An installed template is a template which has been copied into a PROS project.
- Depots: A depot is a connector to a remote template storage. Conductor doesn’t require any particular access method to these remote templates, but they are typically available from a download link via HTTP. It is possible to implement an SCP, FTP, or other sorts of file transfer depots. The default depot is called pros-mainline and is the official repository of templates.
- Projects: A project is a set of user files and template files. They don’t contain much information on their own - just a target platform and a list of installed templates. PROS Conductor maintains two lists of files originating from templates: user files and system files. User files are never replaced when upgrading a project and system files are always replaced when upgrading a project.
Creating a new project¶
Installing/upgrading a new template¶
Fetching a remote template¶
Fetching a local template archive¶
A template is a description of a set of files. All PROS
projects are readily capable of creating a template. Change the following
section in your project’s Makefile. Then, to compile and create the template,
pros make template.
LIBNAMEto a name for your library.
VERSIONto a version for your library.
The default behavior of
pros make template is to compile/package all source
files in your project, except for those listed in
Additionally, any header files which you have created will be bundled. More
concisely, any header files which weren’t added by a template are included.
For advanced usage of creating templates, you can modify the
your own custom arguments to
pros conduct create-template
The following tasks may require you to edit the conductor.pros file. conductor.pros is a configuration file that can be used to influence how PROS Conductor behaves. On Windows, this file is located in
%APPDATA%\PROS. On other systems, consult the Click documentation <https://click.palletsprojects.com/en/5.x/api/#click.get_app_dir> for possible locations.
Editing Default Templates For New Projects¶
By default, new PROS projects ship with OkapiLib. If you want to change this, or add other templates of your own automatically when creating new projects, you can do so as follows.
Open conductor.pros (see above). Find the
default_libraries key. Within this key, you can specify the names of templates included by default for each target (
cortex). For example, if you wanted to make sure that libhotel was added to new projects and not OkapiLib, you might end up with the following
Creating Remote Depots¶
A depot is a collection of templates. Typically, you will have one local depot (managed by the PROS CLI) and one or more remote depots. By default, PROS recognizes one remote depot, maintained by the PROS development team. This points the CLI to download locations for versions of the PROS kernel template as well as OkapiLib, which is included in new projects by default.
It can be somewhat cumbersome for users to apply custom templates to their projects. They must download the zip archive,
pros conduct fetch it into their local depot, then
pros conduct apply it to a project. To make this workflow less annoying, it is possible for template maintainers to create their own remote depots. This process is described below.
The first step is to create a JSON file that is accessible over the internet. PROS does this using the purduesigbots/pros-mainline repository. It is set up with GitHub Pages and configured not to use Jekyll. As a result, the JSON file describing the pros-mainline depot is accessible at https://purduesigbots.github.io/pros-mainline/pros-mainline.json. The JSON file you create should be in the same format as pros-mainline.json: it should be an array of objects with information about each available template.
Once you have a remote depot, you must tell your copy of the PROS CLI about it before the CLI will look for templates in it.
Open conductor.pros (see above). To add a remote depot, look at the depots key. This is a python dict mapping a depot name to a remote depot object. Add a new entry that looks like the following:
making sure to change the name and location to match the ones you set up in the above step. Save the file, and run
pros conduct query --force-refresh to verify that it worked as expected.
If you are a template maintainer providing a remote depot for your users, it may be a good idea to provide your users with a pre-written copy of the depot object needed in conductor.pros, as well as a condensed version of these instructions for how to add it there.
With a custom remote depot, users will be able to install templates specified within by running
pros conduct apply my-template in their projects, and upgrade them by running
pros conduct upgrade my-template without needing to manually download archives.
Changing the Default Target¶
If you use PROS to work primarily with VEX Cortex projects, you can change the default target for new projects to avoid specifying it at project creation time.
Open conductor.pros (see above). Find the
default_target key. The value of this key can be either