Slightly change project directory structure

[ubruhin]

The current directory structure of a LibrePCB project looks like this (not all files shown to improve readability):

MyProject
├── MyProject.lpp
├── boards
│   ├── MyBoard1.lp
│   └── MyBoard2.lp
├── core
│   ├── boards.lp
│   ├── circuit.lp
│   ├── erc.lp
│   ├── metadata.lp
│   ├── schematics.lp
│   └── settings.lp
├── schematics
│   ├── MySchematicPage1.lp
│   └── MySchematicPage2.lp
└── user
    └── boards
        ├── MyBoard1.lp
        └── MyBoard2.lp

But I don't like following things:

• Boards are located in ./boards/, but the list of all boards is in ./core/boards.lp.
• Schematics are located in ./schematics/, but the list of all schematics is in ./core/schematics.lp.
• User settings (not put under version control) are in separate directory ./user/. Currently there is a board subdirectory, which contains a settings file for each board. This is nice because in version control systems, only the user directory needs to be ignored. But the drawbacks are:
  • Related files are spread over different directories (e.g. ./user/boards/MyBoard1.lp is related to ./boards/MyBoard1.lp)
  • It may look like we strictly dictate which files must be put under version control and which not. But actually the user is free to decide which files he wants to ignore and which not. We just provide a reasonable .gitignore, but if for example one wants to also commit board user settings, he could do that.
• If some time boards or schematics need additional resources like DXF or image files, where to put them?

So maybe it would make sense to slightly change the directory structure, for example like this:

MyProject
├── MyProject.lpp
├── boards
│   ├── boards.lp
│   ├── ace706f3-b818-4ce9-86ab-e3185109c18f
│   │   ├── MyBoard1.user.lp
│   │   └── MyBoard1.lp
│   └── 0035f2f4-c0fe-4b64-8830-f4e8fd34d204
│       ├── MyBoard2.user.lp
│       └── MyBoard2.lp
├── core
│   ├── circuit.lp
│   ├── erc.lp
│   ├── metadata.lp
│   └── settings.lp
└── schematics
    ├── schematics.lp
    ├── b45ab168-2941-463d-9fbe-dfb4ed6cebfa
    │   └── MySchematicPage1.lp
    └── e2ecd2de-237c-4f0f-8a1d-085af7f88f4e
        └── MySchematicPage2.lp

So every board and schematic would consist of a whole directory instead of a single file. This would have several advantages:

• Location of boards.lp and schematics.lp is more reasonable (right next to the boards/schematics).
• Files related to a board or schematic (e.g. user settings, DXF, images, whatever in future comes) are located directly in the directory of the corresponding board/schematic. So everything of a board or schematic is located in one directory.
• User-related settings can still easily be ignored. If we introduce a naming convention like the suffix .user.lp for all user related settings, they can be ignored with the pattern *.user.lp. Or even fine-graded control is possible, like ignoring all board user settings with ./boards/*/*.user.lp.

Any opinions?

[rnestler]

I really like that with the new scheme everything related to boards/schematics is actually in the corresponding folder.

If we'd want to avoid UUID's for readabilities sake we could use something like this:

├── boards
│   ├── boards.lp
│   ├── MyBoard1
│   │   ├── board.user.lp
│   │   └── board.lp
│   └── MyBoard2
│       ├── board.user.lp
│       └── board.lp

[ubruhin]

If we'd want to avoid UUID's for readabilities sake we could use something like this:

Yep. Maybe that's better than using the UUID.

In addition, I wonder if the .user.lp suffix is a good idea. We could use more expressive filenames like layer_settings.lp and view_settings.lp, but then the .gitignore needs more entries, for example:

./boards/*/layer_settings.lp
./schematics/*/view_settings.lp

[dbrgn]

Any opinions?

Sounds reasonable :)

I don't have strong opinions on uuid vs .user.lp, but the latter does look more readable.

[rnestler]

In addition, I wonder if the .user.lp suffix is a good idea.

I think .user.lp suffix is kind of intuitive. But we could also use something like .lpu (LibrePcb User) and then have descriptive file names:

• layer_settings.lpu
• view_settings.lpu And just *.lpu in the .gitignore.

Or just use layer_settings.user.lpu.

[rnestler]

I don't have strong opinions on uuid vs .user.lp

Where is it UUID vs. .user.lp? It's more UUID vs Board Name.

[ouabache]

While your at it how about documentation? Be nice to have a place to put it.

How about the symbol for the board? One of your deliverables is a symbol showing all of your connectors and test points that the system architect can place on a schematic with all of the other boards to run a complete system test.

You also need a testbench so that you can do your own test before handing off to the architects.

Do keep the UUIDS out of the file system. It is downright user hostile.

John Eaton

[ubruhin]

I think .user.lp suffix is kind of intuitive.

True.

But we could also use something like .lpu (LibrePcb User) and then have descriptive file names

The disadvantage of this is that it introduces a new mimetype which is (beside its file extension) exactly the same as .lp.

So probably something like layer_settings.user.lp would be most reasonable because

• no need for an additional mimetype, use *.lp for all s-expr files
• user-related files clearly recognizable by the .user.lp suffix
• purpose of file clearly recognizable by its basename

While your at it how about documentation? Be nice to have a place to put it.

Good point, I think I'll add some documentation about this.

How about the symbol for the board? One of your deliverables is a symbol showing all of your connectors and test points that the system architect can place on a schematic with all of the other boards to run a complete system test. You also need a testbench so that you can do your own test before handing off to the architects.

I'm not sure if I understand you correctly, but I think you mean features which are not yet implemented anyway, so it's not really related to this issue. The files needed for these features need to be determined when implementing these features...

Do keep the UUIDS out of the file system.

Yes I'll try to use the board/schematic names also for the corresponding directory names.

One more thing which may make sense is to split the core directory into circuit and project directories to clearly differentiate between the project itself and its circuit.

After all these changes, a project would look like this:

MyProject
├── MyProject.lpp
├── boards
│   ├── boards.lp
│   ├── MyBoard1
│   │   ├── board.lp
│   │   └── settings.user.lp
│   └── MyBoard2
│       ├── board.lp
│       └── settings.user.lp
├── circuit
│   ├── circuit.lp
│   └── erc.lp
├── library
│   └── <<< all library elements used in the project >>>
├── output
│   └── <<< all generated files, e.g. Gerber files, PDF, ... >>>
├── project
│   ├── metadata.lp
│   └── settings.lp
├── resources
│   └── <<< various resources used in the project, e.g. fonts >>>
└── schematics
    ├── schematics.lp
    ├── MySchematicPage1
    │   └── schematic.lp
    └── MySchematicPage2
        └── schematic.lp

[rnestler]

While your at it how about documentation? Be nice to have a place to put it.

Good point, I think I'll add some documentation about this.

I'm not sure if @ouabache meant documentation about this structure or if he meant a folder inside the structure to put documentation about the project.

[ubruhin]

I'm not sure if @ouabache meant documentation about this structure or if he meant a folder inside the structure to put documentation about the project.

Ah, you might be right. Actually the user could just create a directory like docs for documentation, I don't know if and how LibrePCB could do something which helps users in documentation handling...

[ouabache]

I was referring to documentation about the project.

My comment about symbols is a yet to be documented feature. Every schematic needs a "Make Symbol" command that creates a symbol for the the schematic and you need a place to store it.

John Eaton

[ubruhin]

Implemented in https://github.com/LibrePCB/LibrePCB/pull/281.