Defining Subprojects

The user option patcher-subprojects stores a list of subproject descriptors. A subproject descriptor is almost the same as a project descriptor, with a few exceptions:

• Instead of the project directory field (the second field in a project descriptor), you rather specify the name of the project this subproject is based on.
• In addition to the standard project options we've already seen, two subproject options are available:

  :subdirectory

  This lets you specify a subdirectory of the original project's directory in which the whole subproject resides. This subdirectory must be provided relative to the original project's directory.
  

  :files

  This lets you specify a list of files or directories composing the subproject. Each file specification may be provided relative to the subdirectory above, if any, or to the original project's directory. They may also contain wildcards.

  Please note that these subproject options have no corresponding fallback (that would be meaningless). They can't appear in a theme either.

• Subprojects don't have an :inheritance mechanism. Instead, they implicitly inherit from their base project (which in turn can inherit from other projects).

Here are some important remarks about permanent subprojects:

• Permanent subprojects are accessible in exactly the same way as normal projects, that is, via the entry point functions (see Entry Points). A subproject is a project, after all. Because of that, projects and permanent subprojects can't share names. Patcher always looks for subprojects first, and then regular projects.
• A subproject with neither a :subdirectory nor a :files option is exactly the same as the base project, apart from project options that you would override. This can hence be seen as an elegant (or kludgy, depending on the viewpoint) way to define project “variants”.
• Since Patcher doesn't really make a distinction between projects and subprojects, it is possible to work on a temporary subproject based itself on a subproject: simply call one of the entry point functions with a simple prefix argument, and select a permanent subproject when prompted. The effect is then to work on a subsubproject: you can specify an optional subsubdirectory and override the set of files affected by the patch.
• Finally, note that it is even possible to both relocate a project and work on a temporary subproject. In order to do that, use a prefix argument of -1 instead of just 1 (<C-u -1>). And now, try to imagine the brain damage that is caused by using a prefix of -1 and then select a permanent subproject as the base project. The effect is to work on a sub-sub-relocated project....