=============
Project Files
=============

Project layout
==============

A SLiCAP schematic project is organised into a few subdirectories under the
project root, mirroring the SLiCAP Python project structure (plus a ``sch/`` for
the editable drawings):

.. list-table::
   :header-rows: 1
   :widths: 18 82

   * - Directory
     - Contents
   * - ``sch/``
     - Schematic sources (``my_circuit.slicap_sch``) **and their sidecar files**
       (``.ini``, ``.symbols``, ``.cache``) — the files you open and save.
   * - ``cir/``
     - Exported top-level netlists (``my_circuit.cir``).
   * - ``lib/``
     - Subcircuit libraries (``my_circuit.lib``) generated by *Save as
       subcircuit* — see :doc:`hierarchical_blocks`.
   * - ``img/``
     - Exported images (``my_circuit.svg`` / ``my_circuit.pdf``).

The GUI Save / Open / Export dialogs and the :doc:`command-line tools
<netlist_and_export>` default to the matching subdirectory.  The project root is
resolved from the open schematic (the parent of its ``sch/`` folder), so a
schematic opened from any project finds its netlists, images and libraries next
to itself.

Sidecar files
=============

A schematic is **self-contained**: everything it needs to look and behave the
same on another machine travels next to it in ``sch/``.  Saving
``my_circuit.slicap_sch`` creates and maintains a small set of sidecar files
with the same base name.

.. list-table::
   :header-rows: 1
   :widths: 28 72

   * - File
     - Contents
   * - ``my_circuit.slicap_sch``
     - The schematic itself (components, wires, labels, annotations) — the file
       you open and save.
   * - ``my_circuit.ini``
     - This schematic's **style** (line widths, colours, fonts), so it always
       looks as it did when saved.  See :doc:`preferences`.
   * - ``my_circuit.symbols``
     - **Frozen copies** of every symbol the schematic uses, so it renders with
       the exact symbols it was drawn with.  See :doc:`symbol_libraries`.
   * - ``my_circuit.cache``
     - A cache of rendered LaTeX labels, so re-opening is fast.  Created only if
       the schematic actually contains typeset expressions; safe to delete.

Why sidecar files
=================

* **Portability** — copy the ``.slicap_sch`` together with its ``.ini`` and
  ``.symbols`` to another computer and it looks and netlists identically.
* **Reproducibility** — a figure in a book keeps its appearance even if the
  application's default symbols or style change later.
* **No clutter** — the render cache lives next to the schematic, not in a global
  folder that quietly grows over time.  Deleting a project removes all its
  files together.

.. note::

   The ``.ini`` and ``.symbols`` files are part of the project and should be
   kept (and version-controlled) with the schematic.  The ``.cache`` directory
   is regenerated automatically and can be ignored or deleted.