Shared Files

Sometimes you want to share some files between multiple systems. You can do it using a special _shared folder and SHARED: prefix in the file source property.

There are two ways to use the shared resources:

  • You can put the shared resources in the _shared folder in the group folder.

  • You can put the shared resources in the _shared folder in the root of the data folder of system_template (in the system_template/_shared folder).

The _shared folder in the group folder is used for sharing resources inside the group. The _shared folder in the root of the data folder of system_template is visible to all systems. The groupped systems also have access to the global _shared folder but it has lower priority than the group’s _shared folder.

Example:

some_system/_map.py

[
    {
        // Regular resource
        "source": "my_texture.png",
        "target": AUTO
    },
    {
        // Shared resource
        "source": "SHARED:my_shared_texture.png",
        "target": AUTO
    }
]

This configuration means that you can put the my_shared_texture.png either in some_system/my_shared_texture.png or in _shared/my_shared_texture.png. If you crate both files, the local file of the system will be used.

The purpose of the shared resources is to avoid duplicating the files.

Since the use of the shared resouces means that you put resources outside of the system, this means that you can’t just copy the system folder to another project. The system_template implements a solution to this problem. It adds 3 new commands that can be used with the regolith apply-filter command:

  • pack - packs the _shared resources into the system folder.

  • unpack - unpacks the system folders into the _shared folder. If the system is in a group, then it unpacks the system into the _shared folder of the group.

  • undo - undoes the last operation.

A typical workflow of moving the system from project A to project B would be as follows (the examples of the commands and their syntax are explained in the next section):

  1. In project A run the pack command.

  2. Copy the system folder to project B.

  3. In project B run the unpack command.

  4. In project A run the undo command.

You don’t have to unpack the system in project B if you’re not going to share any resources of that system with other systems on the project. In that case, it is recommended to remove the SHARED: prefix from the source properties in the system’s _map.py file. In general, the cleanest solution is to keep all of the shared resources in the _shared folder and to remove the SHARED: prefix if a resource is not shared.

The syntax of the pack, unpack and undo commands

The pack, unpack and undo commands are designed to be used with the regolith apply-filter command. The apply-filter command syntax is:

regolith apply-filter -- <filter_name> <filter_arguments>

In case of the system_template filter, the filter name is always system_template:

regolith apply-filter -- system_template <filter_arguments>

The pack and unpack commands

The pack and unpack commands have their own flags that can be used to specify their behavior:

  • --systems - a list of glob patterns that define which systems should be packed or unpacked. The default value is **/* which means that all systems will be packed or unpacked. You can provide multiple patterns by separating them with a space.

  • --scope - a path to a JSON file that defines the scope that will be used when evaluating the _map.py files. The default value is system_template/scope.json which means that the default scope will be used.

Example: Unpacking my_system using the scope.json file as the scope.

regolith apply-filter -- system_template unpack --systems my_system --scope scope.json

The undo command

The undo command has no flags. It undoes the last pack or unpack operation.

Example: Undoing the last operation.

regolith apply-filter -- system_template undo