In Ringdove, a project is a directory with a set of design files (potentially symlinks) and an optional project file, project.lht. The project file, when exists, serves two purposes:
If the project file has a design file list, the design files do not need to be in the same directory as the project file (more on this later).
In sch-rnd we can compile (and then export) a project, not a sheet. In fact this happens in gschem too, it's just a bit hidden there: if you don't want to break your multi-sheet design, you always need to pass all sheet files to gnetlist. Running gnetlist on less sheets or on just one sheet will yield the wrong netlist. Since gnetlist doesn't handle project files, it's you, the user, who has to remember (or write a script) to pass all sheets.
Sch-rnd makes this more explicit: instead of "gafrc" that's almost a project file, but it's not, sch-rnd has a real project file, project.lht, which can list sheet names.
The most trivial case: the whole project is a single sheet (small project). It's also useful if there are multiple projects using a generic, shared sheet, some sort of building block, which needs to be fixed or upgraded.
In this case the design file is open directly, by its file name. Sch-rnd will go and automatically load the config part of project.lht from the same dir, but the file listing in project.lht will not cause loading of extra files.
If project.lht lists more or different root sheets than the one loaded, the compiler will throw an error on partial compilation. This means not all sheets are loaded which makes up the project so the compiler worked from partial input which resulted in a partial abstract model.
This works in sch-rnd because of MDPP. If multiple sheets of the same project is loaded, sch-rnd figures they are for the same project. It's also possible to open multiple sheets of multiple projects, in which case sch-rnd is aware of which sheet consists of which project (and presents the situation as a tree of project/sheet).
It is also possible to name a few sheets of a project, but not all sheets of the project. In which case compilation would break, as compilation works only on projects. Detecting the situation is simple:
The compiler throws a partial compilation error in this case; however if all sheets are loaded which are named on the root sheets in project.lht, the compilation is not partial, and no error is generated.
Note: the important aspect of MS is that we do not open sheet files by the project file's sheet file listing, but manually specifying sheet names.
Opening a project.lht will open all sheets listed by that project.lht. This is how a complete project can be loaded easily.
This assumes the project file does have a sheet file name list, else it fails.
Partial compilation is possible only if the project file names a sheet file that can not be loaded (e.g. not found or has errors).
Corner #1: let's say we have a directory with project.lht with no sheet listing and we load a.lht, b.lht and c.lht from that dir then hit compile. This is an MDPC situation: project file has no sheet list (only config, if it exists). For compilation we have to assume all relevant files are loaded and work from what we have.
Corner #2: let's say we have a directory with project.lht listing a.lht and b.lht, but the user loads sheets a.lht, b.lht and c.lht from that dir. What happens to the sheets? Solution: for project configuration, all a.lht, b.lht and c.lht share the same project.lht. For compilation, this is an MDPP case: project file does have sheet list. We know we need to use all sheets listed there for the compilation. We see both a.lht and b.lht are loaded so the project is complete and we can compile. Plus we see c.lht is not on project.lht's list so we need to ignore c.lht even if it is loaded from the same dir. So for c.lht project.lht provides only the config. The compiler trhows a warning about not compiling c.lht, and c.lht is marked "unlisted" ont he user interface.
Corner #3: what to do when partially loaded project is being compiled? Imagine the above project file listing a.lht, b.lht and e.lht, but we run sch-rnd and load only a.lht and b.lht but not e.lht.
In this case the compiler still runs, but throws a bold error on partial compilation. The user needs to understand the resulting abstract model is also partial, so will be any export (e.g. netlist).
There is menu to load all sheets that are not already loaded..
Corner #4: at the end two setups must work: when a single sheet is open and when a whole project is open. The above setup with all possible scenarios is rather complex, which could be simplified by not allowing partial projects (when there's a project file with a sheet list but not all, but only one or a few sheets are open). Which means:
However, this would pretty much enforce using projects, which is not necessarily a good thing. At the moment I think it's better to go with allowing partial loads but knowing they are partial (and throw an error in the compiler but still do the job).
Corner #5: another possible simplification is leaving out file listing from the project file, saying all sheets (and boards) within the directory is what makes up the project, so if a full project is to be loaded just list files and check which ones have the right header. However, this has a lot of drawbacks:
Thus the design decision has been made for explicit design file listing i project file.
Long term most of the project/design handling code lands in librnd and pcb-rnd will be able to edit multiple sheets _and_ projects too. However, pcb-rnd does not have compilation so some of the above corner cases don't apply.
The conceptual difference is this:
How can pcb-rnd still benefit from multi-board/project approach: