Core Libraries

Overview

KiCad’s architecture is built on a foundation of specialized libraries that provide reusable functionality across all applications. These libraries are organized in a dependency hierarchy, with lower-level libraries having no dependencies on higher-level code.

Library Dependency Hierarchy

libs/core (foundation)
    ↓
libs/kimath, kiplatform, sexpr, kinng
    ↓
common (application framework)
    ↓
Application DSOs (eeschema, pcbnew, etc.)

Foundation Libraries (`libs/`)

`libs/core`

Purpose: Foundation library with no external KiCad dependencies Description: Provides basic utilities and extensions to standard libraries. This is the lowest-level library and should never depend on any KiCad-specific code. Components:

base64.cpp: Base64 encoding and decoding for binary data serialization
utf8.cpp: UTF-8 string handling and conversion utilities
observable.cpp: Observer pattern implementation for event notification
profile.cpp: Performance profiling and timing utilities
version_compare.cpp: Semantic version parsing and comparison
wx_stl_compat.cpp: Compatibility layer between wxWidgets and STL

Use cases:

String encoding for file I/O
Performance measurement
Event-driven architecture
Version management

`libs/kimath`

Purpose: Mathematical and geometric algorithms Description: Provides computational geometry, vector math, and algorithms used throughout KiCad for design calculations. Key components:

Geometry primitives:
- VECTOR2<T> - 2D vector with templated precision
- BOX2<T> - Axis-aligned bounding box
- SEG - Line segment with intersection algorithms
- SHAPE - Base class for geometric shapes
Shape classes:
- SHAPE_LINE_CHAIN - Polyline with arcs
- SHAPE_POLY_SET - Complex polygon with holes using Clipper library
- SHAPE_CIRCLE - Circle primitive
- SHAPE_ARC - Circular arc segment
- SHAPE_RECT - Rectangle
- SHAPE_COMPOUND - Composite of multiple shapes
Algorithms:
- Polygon intersection and union (via Clipper2)
- Point-in-polygon testing
- Distance calculations
- Convex hull computation
- Polygon offsetting (clearance zones)
- Boolean operations
- Bezier curve evaluation

Use cases:

Copper pour calculations
Collision detection
Clearance validation
Design rule checking
Keepout zone management

`libs/kiplatform`

Purpose: Operating system abstraction layer Description: Provides platform-specific functionality with a unified API, isolating OS differences. Platform support:

Linux (GTK3/Wayland/X11)
Windows
macOS

Functionality:

Application integration:
- Window manager hints
- Desktop environment integration
- System tray/dock support
- File association handling
Hardware access:
- GPU detection and capabilities
- Display scaling (HiDPI)
- 3D mouse support (SpaceMouse)
- Keyboard layout detection
File system:
- Path normalization
- Temporary directory management
- System directory locations
- Permission handling
Security:
- Sandboxing support
- Privilege escalation (when needed)
- Certificate validation

Architecture:

namespace KIPLATFORM
{
    namespace ENV { /* Environment variables */ }
    namespace APP { /* Application lifecycle */ }
    namespace UI { /* User interface integration */ }
    namespace IO { /* File system operations */ }
}

`libs/sexpr`

Purpose: S-expression parser and serializer Description: Fast, lightweight S-expression handling used for KiCad’s native file formats. Features:

Recursive descent parser
Streaming support for large files
Efficient memory usage
Error reporting with line numbers

Example format (from .kicad_sch files):

(kicad_sch
  (version 20250610)
  (generator "eeschema")
  (uuid "1b112ac5-701b-420f-be34-0e29a2cb55ca")
  (paper "A3")
  (lib_symbols
    (symbol "Resistor"
      (property "Reference" "R")
      (property "Value" "10k")
    )
  )
)

Use cases:

Schematic files (.kicad_sch)
PCB files (.kicad_pcb)
Symbol libraries (.kicad_sym)
Footprint files (.kicad_mod)

`libs/kinng`

Purpose: NNG (nanomsg) wrapper for IPC Description: Message queue implementation for the KiCad IPC API, enabling external tool communication. Features:

Request/response patterns
Publish/subscribe messaging
Pipeline communication
Survey/respondent patterns

Use cases:

External automation tools
CI/CD integration
Custom scripting environments
Third-party plugin communication

Configuration: Only built when KICAD_IPC_API is enabled.

Common Library (`common/`)

Overview

The common library provides the application framework shared by all KiCad applications. It’s significantly larger than the foundation libraries and contains most of the EDA-specific functionality.

Tool Framework (`common/tool/`)

Purpose: Event-driven interactive tool architecture Key classes:

`TOOL_MANAGER`

Manages tool lifecycle and event dispatch:

class TOOL_MANAGER
{
    void RegisterTool( TOOL_BASE* aTool );
    void InvokeTool( TOOL_ID aToolId );
    bool RunAction( const TOOL_ACTION& aAction );
    void ProcessEvent( const TOOL_EVENT& aEvent );
};

`TOOL_ACTION`

Defines discrete user actions:

TOOL_ACTION PCB_ACTIONS::drawLine(
    "pcbnew.InteractiveDrawing.line",
    AS_GLOBAL,
    MD_SHIFT + 'L',
    _("Draw Line"),
    _("Draw a line")
);

`TOOL_EVENT`

Represents user input events:

Mouse events (click, drag, move)
Keyboard events
Action triggers
Tool-specific events

`TOOL_DISPATCHER`

Routes OS events to tools:

Converts wxWidgets events to TOOL_EVENT
Manages event queue
Handles event propagation

Benefits:

Decoupled tool implementation
Testable without UI
Keyboard shortcut management
Context-sensitive actions

Graphics Abstraction Layer (`common/gal/`)

Purpose: Hardware-accelerated 2D rendering Backends:

OpenGL

GPU-accelerated rendering
Vertex buffer objects (VBO)
Shader-based pipeline
Best performance for large designs

Cairo

Software fallback
Print output
PDF/SVG generation
Consistent output across platforms

Architecture:

class GAL // Graphics Abstraction Layer
{
    virtual void DrawLine( VECTOR2D start, VECTOR2D end );
    virtual void DrawCircle( VECTOR2D center, double radius );
    virtual void DrawPolygon( const SHAPE_POLY_SET& poly );
    
    void SetStrokeColor( COLOR4D color );
    void SetFillColor( COLOR4D color );
    void SetLineWidth( double width );
};

Features:

Layer compositing
Anti-aliasing
Grid rendering
Cursor management
Pick-and-place optimization
Bitmap caching for static elements

View System (`common/view/`)

Purpose: Canvas and viewport management Key classes:

`VIEW`

Manages visible items and layers:

class VIEW
{
    void Add( VIEW_ITEM* item );
    void Remove( VIEW_ITEM* item );
    void Update( VIEW_ITEM* item );
    void SetCenter( VECTOR2D center );
    void SetScale( double scale );
};

`VIEW_ITEM`

Base class for renderable objects:

class VIEW_ITEM
{
    virtual BOX2I ViewBBox() const;
    virtual void ViewDraw( int layer, VIEW* view ) const;
    virtual void ViewGetLayers( int layers[], int& count ) const;
};

`PAINTER`

Rendering strategy:

class PAINTER
{
    virtual void Draw( const VIEW_ITEM* item, int layer );
    RENDER_SETTINGS* GetSettings();
};

Features:

Spatial indexing (R-tree)
Dirty region tracking
Layer visibility control
Z-order management
Viewport clipping

I/O Framework (`common/io/`)

Purpose: File format parsers and writers Supported formats:

Native KiCad

S-expression based (.kicad_*)
Legacy formats (older versions)

Import formats

Altium: .PcbDoc, .SchDoc
EAGLE: .brd, .sch
EasyEDA: JSON-based
CADSTAR: Archive formats
PADS: .asc, .dra
Gerber: RS-274X
DXF/DWG: CAD exchange
IDF: Board outlines

Architecture:

class IO_BASE
{
    virtual void Save( const wxString& filename, 
                       BOARD* board, 
                       const STRING_UTF8_MAP* props = nullptr ) = 0;
                       
    virtual BOARD* Load( const wxString& filename,
                         BOARD* board,
                         const STRING_UTF8_MAP* props = nullptr ) = 0;
};

Plugin registration: Each format has a dedicated plugin implementing the IO interface.

Settings Management (`common/settings/`)

Purpose: Configuration persistence and migration Key components:

`JSON_SETTINGS`

Base settings class:

class JSON_SETTINGS
{
    bool LoadFromFile();
    bool SaveToFile();
    nlohmann::json& At( const std::string& path );
};

Settings types

Application settings: Per-application preferences
Project settings: Per-project configuration
Color themes: Rendering preferences
Library tables: Symbol/footprint paths

Migration

Version tracking
Automatic upgrades
Backwards compatibility

Font Rendering (`common/font/`)

Font types:

Stroke Font

Vector-based (lines and arcs)
Compact representation
Fast rendering
Used for default text

Outline Font

TrueType/OpenType support
HarfBuzz shaping
FreeType rendering
Better typography

Text rendering pipeline:

Font selection
Text shaping (HarfBuzz)
Glyph rasterization (FreeType)
GAL drawing commands

Plotters (`common/plotters/`)

Purpose: Manufacturing output generation Formats:

Gerber (RS-274X): PCB fabrication
PDF: Documentation
SVG: Web and documentation
DXF: CAD exchange
HPGL: Legacy plotting
PostScript: Printing

Architecture:

class PLOTTER
{
    virtual void StartPlot();
    virtual void EndPlot();
    virtual void SetColor( const COLOR4D& color );
    virtual void PlotPoly( const std::vector<VECTOR2I>& pts );
};

KIWAY Architecture

Purpose

KIWAY is KiCad’s inter-module communication system, enabling separate DSOs (Dynamic Shared Objects) to communicate within a single process.

Key Concepts

KIFACE (KiCad Interface)

struct KIFACE
{
    bool OnKifaceStart( PGM_BASE* program, int ctlBits, KIWAY* kiway );
    void OnKifaceEnd();
    wxWindow* CreateKiWindow( wxWindow* parent, int classId, KIWAY* kiway );
    void* IfaceOrAddress( int dataId );
};

Each application module (eeschema, pcbnew) implements KIFACE.

KIWAY (Communication Bus)

class KIWAY
{
    enum FACE_T {
        FACE_SCH,      // Eeschema
        FACE_PCB,      // Pcbnew  
        FACE_CVPCB,
        FACE_GERBVIEW,
        // ...
    };
    
    KIFACE* KiFACE( FACE_T face );
    KIWAY_PLAYER* Player( FRAME_T frameType );
    void ExpressMail( FRAME_T dest, MAIL_T cmd, std::string& payload );
};

Benefits:

Loose coupling between modules
Dynamic loading of DSOs
Python integration per module
Separate compilation units
Memory isolation

Message Passing

ExpressMail: Send commands between modules

// From project manager to eeschema
Kiway().ExpressMail(
    FRAME_SCH,
    MAIL_OPEN_FILE,
    schematicPath
);

Use cases:

Opening files across applications
Synchronizing project state
Cross-probing (schematic ↔ PCB)
Updating netlists

Contributing

Architecture

API Reference

​Overview

​Library Dependency Hierarchy

​Foundation Libraries (libs/)

​libs/core

​libs/kimath

​libs/kiplatform

​libs/sexpr

​libs/kinng

​Common Library (common/)

​Overview

​Tool Framework (common/tool/)

​TOOL_MANAGER

​TOOL_ACTION

​TOOL_EVENT

​TOOL_DISPATCHER

​Graphics Abstraction Layer (common/gal/)

​OpenGL

​Cairo

​View System (common/view/)

​VIEW

​VIEW_ITEM

​PAINTER

​I/O Framework (common/io/)

​Native KiCad

​Import formats

​Settings Management (common/settings/)

​JSON_SETTINGS

​Settings types

​Migration

​Font Rendering (common/font/)

​Stroke Font

​Outline Font

​Plotters (common/plotters/)

​KIWAY Architecture

​Purpose

​Key Concepts

​KIFACE (KiCad Interface)

​KIWAY (Communication Bus)

​Message Passing

​See Also

Build docs developers (and LLMs) love

Overview

Library Dependency Hierarchy

Foundation Libraries (`libs/`)

`libs/core`

`libs/kimath`

`libs/kiplatform`

`libs/sexpr`

`libs/kinng`

Common Library (`common/`)

Overview

Tool Framework (`common/tool/`)

`TOOL_MANAGER`

`TOOL_ACTION`

`TOOL_EVENT`

`TOOL_DISPATCHER`

Graphics Abstraction Layer (`common/gal/`)

OpenGL

Cairo

View System (`common/view/`)

`VIEW`

`VIEW_ITEM`

`PAINTER`

I/O Framework (`common/io/`)

Native KiCad

Import formats

Settings Management (`common/settings/`)

`JSON_SETTINGS`

Settings types

Migration

Font Rendering (`common/font/`)

Stroke Font

Outline Font

Plotters (`common/plotters/`)

KIWAY Architecture

Purpose

Key Concepts

KIFACE (KiCad Interface)

KIWAY (Communication Bus)

Message Passing

See Also