Development Environment

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/KiCad/kicad-source-mirror/llms.txt

Use this file to discover all available pages before exploring further.

​

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

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

​

Recommended Development Tools

​

Code Editors and IDEs

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

• Full CMake integration
• Built-in debugger
• Code analysis tools

• CMake support
• Good C++ support

• 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

1. Fork the repository on GitLab:
   • Navigate to https://gitlab.com/kicad/code/kicad
   • Click “Fork”
2. Clone your fork:
   git clone git@gitlab.com:YOUR_USERNAME/kicad.git
   cd kicad
   
3. Add upstream remote:
   git remote add upstream https://gitlab.com/kicad/code/kicad.git
   

​

Configure Your GitLab Fork

1. Settings → General → Visibility
   • CI/CD should be enabled and set to “Everyone with access”
2. Settings → CI/CD → General pipelines
   • Timeout should be set to 3 hours or longer
3. 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

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)

​

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

​

Incremental Builds

cd build/debug
make -j$(nproc)

​

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

(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

• 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)

• Data races
• Deadlocks

​

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

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

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

​

Code Formatting

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

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

​

Performance Optimization

​

Using ccache

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

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

​

Using Precompiled Headers

-DKICAD_USE_PCH=ON  # Default

​

Parallel Builds

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

​

Platform-Specific Notes

​

Linux

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

-DKICAD_WAYLAND=ON  # Default on Linux

​

macOS

xcode-select --install

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

​

Windows

cmake ../.. -DKICAD_WIN32_BUILD_PARALLEL_CL_MP=ON

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

​

Troubleshooting

​

Build Cache Issues

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

​

IDE Not Finding Headers

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

​

Library Version Conflicts

​

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

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