Development Environment

This guide helps you set up an efficient development environment for working on KiCad.

Development Tools

Essential Tools

Version Control

Git - Version control system
GitLab account - For hosting your fork and submitting merge requests

Build System

CMake 3.22+ (3.28.1+ for MSVC ARM)
Make or Ninja build system
ccache (optional) - Speeds up recompilation
distcc (optional) - Distributed compilation

Compilers

KiCad requires C++20 support:

GCC 10+ (Linux)
Clang 11+ (macOS, Linux)
MSVC 2019+ (Windows)

Recommended Development Tools

Code Editors and IDEs

Visual Studio Code

C/C++ extension
CMake Tools extension
GitLens extension
clang-format extension

CLion

Full CMake integration
Built-in debugger
Code analysis tools

Qt Creator

CMake support
Good C++ support

Vim/Neovim

YouCompleteMe or coc.nvim for code completion
vim-cmake plugin

Debugging Tools

GDB (Linux)
LLDB (macOS, Linux)
Visual Studio Debugger (Windows)
Valgrind - Memory debugging and profiling
Address Sanitizer (ASan) - Memory error detection
Thread Sanitizer (TSan) - Data race detection

Setting Up Your Environment

Fork and Clone the Repository

Fork the repository on GitLab:
- Navigate to https://gitlab.com/kicad/code/kicad
- Click “Fork”

Clone your fork:

git clone [email protected]:YOUR_USERNAME/kicad.git
cd kicad

Add upstream remote:

git remote add upstream https://gitlab.com/kicad/code/kicad.git

Configure Your GitLab Fork

Configure your personal fork with the following settings:

Settings → General → Visibility
- CI/CD should be enabled and set to “Everyone with access”
Settings → CI/CD → General pipelines
- Timeout should be set to 3 hours or longer
When creating merge requests
- Check “Allow commits from members who can merge to the target branch” at the bottom of your merge request

Build Directory Structure

Recommended directory layout:

kicad/
├── .git/
├── build/
│   ├── debug/          # Debug builds
│   ├── release/        # Release builds
│   └── qa/             # QA builds
├── CMakeLists.txt
├── eeschema/
├── pcbnew/
└── ...

Initial Build Setup

Debug Build

mkdir -p build/debug
cd build/debug
cmake ../.. \
  -DCMAKE_BUILD_TYPE=Debug \
  -DCMAKE_EXPORT_COMPILE_COMMANDS=ON \
  -DKICAD_STDLIB_LIGHT_DEBUG=ON \
  -DUSE_CCACHE=ON
make -j$(nproc)

The CMAKE_EXPORT_COMPILE_COMMANDS=ON option generates compile_commands.json, which many IDEs and language servers use for code intelligence.

Release Build for Testing

mkdir -p build/release
cd build/release
cmake ../.. \
  -DCMAKE_BUILD_TYPE=Release \
  -DCMAKE_EXPORT_COMPILE_COMMANDS=ON
make -j$(nproc)

Development Workflow

Keeping Your Fork Updated

# Fetch latest changes from upstream
git fetch upstream

# Update your local master branch
git checkout master
git merge upstream/master

# Push to your fork
git push origin master

Creating a Feature Branch

# Create and switch to a new branch
git checkout -b feature/my-new-feature

# Make your changes...

# Commit your work
git add <files>
git commit -m "Add new feature"

# Push to your fork
git push origin feature/my-new-feature

Always create new branches for merge requests instead of using your fork’s master branch.

Incremental Builds

After making code changes:

cd build/debug
make -j$(nproc)

CMake will automatically detect changed files and rebuild only what’s necessary.

Running Tests

cd build/debug
ctest --output-on-failure

# Run specific test
ctest -R test_name --output-on-failure

# Run tests in parallel
ctest -j$(nproc) --output-on-failure

Debugging

Using GDB (Linux)

cd build/debug
gdb ./kicad/kicad

Common GDB commands:

(gdb) run                    # Start the program
(gdb) break main.cpp:123     # Set breakpoint
(gdb) continue               # Continue execution
(gdb) next                   # Step over
(gdb) step                   # Step into
(gdb) print variable         # Print variable value
(gdb) backtrace              # Show call stack

Using Sanitizers

Address Sanitizer

cmake ../.. \
  -DCMAKE_BUILD_TYPE=Debug \
  -DKICAD_SANITIZE_ADDRESS=ON
make -j$(nproc)
./kicad/kicad

ASan will detect:

Use-after-free
Heap/stack/global buffer overflow
Use-after-scope
Memory leaks

Thread Sanitizer

cmake ../.. \
  -DCMAKE_BUILD_TYPE=Debug \
  -DKICAD_SANITIZE_THREADS=ON
make -j$(nproc)

TSan will detect:

Data races
Deadlocks

Warning: Do not use sanitizers with the gold linker.

Using Valgrind

# Build with Valgrind support
cmake ../.. \
  -DCMAKE_BUILD_TYPE=Debug \
  -DKICAD_USE_VALGRIND=ON
make -j$(nproc)

# Run with Valgrind
valgrind --leak-check=full ./kicad/kicad

Code Intelligence and Formatting

compile_commands.json

CMake generates compile_commands.json in your build directory (when CMAKE_EXPORT_COMPILE_COMMANDS=ON is set). Many tools use this:

clangd language server
VSCode C++ extension
CLion
vim-clang

Create a symlink in your source root:

ln -s build/debug/compile_commands.json compile_commands.json

Code Formatting

KiCad uses clang-format for code formatting. The configuration is in _clang-format at the repository root. Format a file:

clang-format -i path/to/file.cpp

Check formatting without modifying:

clang-format --dry-run --Werror path/to/file.cpp

See the Code Style guide for more details.

Performance Optimization

Using ccache

ccache speeds up recompilation by caching previous compilations:

# Install ccache
sudo apt-get install ccache  # Ubuntu/Debian
sudo dnf install ccache      # Fedora

# Enable in CMake
cmake ../.. -DUSE_CCACHE=ON

Using Precompiled Headers

KiCad uses precompiled headers by default to speed up builds:

-DKICAD_USE_PCH=ON  # Default

Parallel Builds

Always use parallel builds:

make -j$(nproc)      # Linux/macOS
cmake --build . -j 8  # Cross-platform

Platform-Specific Notes

Linux

GTK3 Development Files Required:

sudo apt-get install libgtk-3-dev  # Ubuntu/Debian
sudo dnf install gtk3-devel        # Fedora

Wayland Support: KiCad supports Wayland natively on Linux:

-DKICAD_WAYLAND=ON  # Default on Linux

macOS

Xcode Command Line Tools:

xcode-select --install

Homebrew Dependencies:

brew install cmake wxwidgets boost python swig glm cairo pixman \
  libgit2 curl ngspice opencascade protobuf

Windows

MSVC with parallel compilation:

cmake ../.. -DKICAD_WIN32_BUILD_PARALLEL_CL_MP=ON

Using vcpkg for dependencies:

cmake ../.. -DCMAKE_TOOLCHAIN_FILE=C:/vcpkg/scripts/buildsystems/vcpkg.cmake

Troubleshooting

Build Cache Issues

If you encounter strange build errors:

# Clean and rebuild
cd build/debug
rm -rf *
cmake ../..
make -j$(nproc)

IDE Not Finding Headers

Ensure compile_commands.json is generated and symlinked
Rebuild the project to update the compile commands
Restart your IDE/language server

Library Version Conflicts

Use the exact library versions that CI uses. Check .gitlab-ci.yml in the repository for reference.

Additional Resources

Developer Docs: https://dev-docs.kicad.org
GitLab CI Pipeline: Check CI configuration for build examples
Doxygen Documentation: Generated from source code comments
Developers Mailing List: https://groups.google.com/a/kicad.org/g/devlist

Next Steps

Review the code style guidelines
Start with a starter issue
Learn how to submit merge requests

Contributing

Architecture

API Reference

​Development Tools

​Essential Tools

​Version Control

​Build System

​Compilers

​Recommended Development Tools

​Code Editors and IDEs

​Debugging Tools

​Setting Up Your Environment

​Fork and Clone the Repository

​Configure Your GitLab Fork

​Build Directory Structure

​Initial Build Setup

​Debug Build

​Release Build for Testing

​Development Workflow

​Keeping Your Fork Updated

​Creating a Feature Branch

​Incremental Builds

​Running Tests

​Debugging

​Using GDB (Linux)

​Using Sanitizers

​Address Sanitizer

​Thread Sanitizer

​Using Valgrind

​Code Intelligence and Formatting

​compile_commands.json

​Code Formatting

​Performance Optimization

​Using ccache

​Using Precompiled Headers

​Parallel Builds

​Platform-Specific Notes

​Linux

​macOS

​Windows

​Troubleshooting

​Build Cache Issues

​IDE Not Finding Headers

​Library Version Conflicts

​Additional Resources

​Next Steps

Build docs developers (and LLMs) love