The project file can host any config setting from the sch-rnd config tree. Config nodes specified in the project file are read on the project role. This provides an easy way to specify project-global settings; settings that may differ from project to project and distributed along with the project.
An important config subtree, which is restricted to be accepted only from the project file, is /prj. This subtree contains list of sheet files.
Example project file:
The root is called coraleda-project-v1 because the project file concept covers not only Ringdove, but the external/satellite projects in the CoralEDA project around Ringdove.
There is a subtree per software, ours is sch-rnd-conf-v1. The overwrite subtree ensures any value under it will overwrite lower priority previous values for the same settings. The node editor/auto_place is a generic config node, randomly picked for the example.
The prj subtree holds settings that can be specified only in the project file. root_sheets is a list of file names (paths relative to the project file) that make up the first level of the hierarchy. In a single-sheet project or a multi-sheet flat project all sheets are listed here.
In a hierarchical project some of the root sheets will refer to non-root sheets which may refer to further non-root sheets. These non-root sheets are called auxiliary sheets. All sheets ever needed for compilation must be listed, either on the root sheet list or on the aux sheet list.
When the project file is opened by sch-rnd GUI or it needs to be packed up for distribution, all sheet files named in root and aux lists shall be included. When the project is compiled, only the root sheets need to be compiled; aux sheets will be reached through hierarchical references starting from root sheets.
Note: a project file is valid even if it does not list any sheet file. In this case it holds project level configuration and file names need to be supplied through another method. However, this approach is less favored than sheet lists in project file because sch-rnd has less understanding of the project.