# 1. The system

## 1.1. What is cschem

{des1:0} The purpose of this chapter is to define what cschem is, what major components it contains and how these components are interacting with the user and 3rd party software. This chapter provides a low resolution system map.

### 1.1.1. Cschem as a concept

{des1:1} Cschem is a system for storing, displaying, editing, transforming (importing, exporting, filtering, generating, etc.) schematics data.

{des1:2} Schematics data is the logical schematics of a system, describing a system on an abstract level, optionally with directives, hints, suggestions or recommendations on the physical implementations/properties.

{des1:3} More specifically, cschem operates on projects. A project is either a single schematics page or cosists of a project file and multiple schematic pages and/or data files.

{des1:4} A typical example is an electric schematics. While cschem is not limited to electronics, this design document will use electronics in most of the examples.

{des1:5} Example: when used with electronics, cschem's role is to handle the schematics drawing, which specifies the components and their logical connections. The schematics is typically the main source for other processes, such as simulation, PCB layout, part purchase, etc.

{des1:6} This flexibility is achieved by attaching attributes to every object type in the data model. Attributes are simple, typically user defined key=value fields. Various tools in the toolchain may read and write different set of attributes. The meaning of most attributes is defined only by conventions. More about attributes can be found in chapter 4.

### 1.1.2. Cschem as a software package: sch-rnd

{des1:7} When the above concepts are implemented as a software package, called "a cschem implementation" or "a cschem package". The official implementation of the cschem concept is sch-rnd. Alternative implementations of the same concepts may exist. These implementations must be compatible on the conceptual level but might be incompatible in implementation details (including file formats).

{des1:8} The official implementation is a small, flexible, portable, modular, extensible set of tools. This chapter describes some of the implementation details of the official package. These implementation details should not affect other implementations.

## 1.2. Components and modules

### 1.2.1. Main components

{des1:9} sch-rnd consists of two major components: frontend and engine. Both components are defined as a group of smaller modules.

{des1:22} (Note: the above diagram does not contain every single subcomponent and plugin, it rather illustrates the main groups. Later chapters will enumerate subcomponents and describe them in detail.)

The job of the engine is to:

- {des1:10} run the data model: store, retrieve, execute simple operations on it
- {des1:11} run an infrastructure for plugins to access the data model in a controlled way
- {des1:12} load, unload, select and run the actual plugins for the given project

The job of the frontend is to:

- {des1:13} provide user interfaces to let the user interactively manipulate project data
- {des1:14} provide user interfaces to let the user manipulate project data in batch mode (automated and semi-automated processing)

### 1.2.2. Engine modules

{des1:15} Majority of the functionality the engine provides is implemented in modules, which are replaceable plugins. There are typical ways a module behaves:

- {des1:16} many of the modules are reading attributes and generating/updating/maintaining other attributes on the fly. For example in an electronics setup the slotting mechanism is a module that reads slotting related configuration attributes to produce actual pin number attributes.
- {des1:17} some modules read one kind of data and generate/update/maintain another kind of data. For example a DRC module would read project data and produce a "list-of-objects-and-comments" about warnings and errors.
- {des1:18} communication to 3rd party software, e.g. "netlist" output would be generated by converter modules; these read the data model and typically produce a file in a file format specified by a 3rd party project
- {des1:19} all data of the data model will eventually need to be saved to or loaded from disk (or the cloud); this is done by I/O modules. They are also responsible for accessing (local or remote) libraries. Questions like file formats, versioning, access methods are all local implementation details of the given I/O module.

{des1:20} The current project loaded will determine which modules should be active. For example there might be multiple implementations of DRC or slotting; each implementation would have an unique name and API version; the project would contain requirements and recommendations as of what modules are needed for proper operation, including which slotting plugin (if any). This is called the project's module dependency list.

{des1:21} A project can have multiple different module dependency lists (views). For example a different slotting mechanism can be used when data is sent to the simulator and when it is sent to the pcb layout tool. The frontend should let the user to specify or select which module dependency list should be used. On an interactive UI it shall be easy to switch between the dependency lists.

{des1:25} How the frontend presents (displays, edits, navigates) the schematics data usually depends on the view selected. (Some details that direct the frontend in the presentation may be plugin-calculated.)

{des1:26} A view contains an ordered list of engines and optionally attributes for each engine, that configures the engine for the view in an engine-specific way. The same engine may be present on the list multiple times (with or without different attributes).

{des1:22} The user can extend cschem by loading user script into the Engine. User scripts can serve in any role listed above.

{des1:23} The project may include arbitrary, plugin-specific data that will be used by a plugin the project depends on (e.g. by an user script; it is the user's responsibility to make sure the formatting of the data matches the expectation of the plugin and the plugin is loaded).

{des1:24} Another source of data is libraries. There are plugins that access local or remote libraries for data that then can be copied into project repositories or can be referenced from project repositories.