kicad/Documentation/compiling/COMPILING.txt

Compiling KiCad from Source
===========================
KiCad Documentation Team
Last revised on 2014-december-24 by JP Charras

Introduction
------------
This is a generic guide how to compile kicad from scratch. On windows and linux.
If you need something more distribution specific or the experimental mac-osx port
read the other documents in the Documentation/compiling folder.

Installation of Tools
---------------------
On windows:

Get msys and mingw here:
http://mingw.org/
msys sets up a development environment that allows the bash shell to run.
mingw are a set of tools that run on windows or under msys.  You will need
at least the following mingw packages: make, gcc, g++, binutils, autoconf, and
automake.

On linux:

Install "mesa".  Use your package manager to install the
development libaries.

After a fresh install you need the following packages to compile and run
KiCad from source.

* bzr     - Bazaar version control system
* CMake   - Cross-platform make
* GLUT    - The OpenGL Utility Library
* GLEW
* wxWidgets  - The wxWidgets GUI toolkit with GTK+ bindings version 3.0 or more
* libbz2    (dev)
* libcairo  (dev)

* Boost   - Collection of portable C++ source libraries
boost will be automagically downloaded, copied in kicad sources tree and patched,
the first time you compile kicad.

Useful, but not required:
* Doxygen - Documentation system for several programming languages

Required to build Kicad with scripting (using python) support:
Python
Swig

KiCad uses the Bazaar version control system to track source code changes,
and download the boost libraries needed by Kicad.
Be sure you bzr install also includes bzrtools.
boost libraries will be downloaded the first time you build Kicad.

Compiler and basic development tools
-------------
Make sure g++, make and other tools are in your path.
If windows, then try running g++ and make from within your msys bash shell.

PLEASE NOTE: g++ 4.7.1 and 4.7.2 are known to
miscompile pcbnew (it get zones wrong) with -O2; using -O1 is a suitable
workaround until they fix the compiler.

Install or Build wxWidgets
--------------------------

WARNING:
 see wxWidgets_patch_notes.txt for patches and issues in wxWidgets.

On Windows, download
http://sourceforge.net/projects/wxwindows/files/3.0.2/wxWidgets-3.0.2.zip/download
or a newer version.
Do NOT use previous versions which all have annoying issues for KiCad.
Start msys so you have a bash shell.
Note also since 2.9 versions no need to build a "debug" version of the wxWidgets library,
the release and the debug version are same.

Unzip the wxWidgets zip file into the build directory.  Change directories into
there, and then:

    mkdir Release
    cd Release
    ../configure --with-opengl
    make

    and under Linux, but not under Windows:
    sudo make install that install wxWidgets libs and headers in /usr/local/


On linux, yo can also download wxWidgets 3.0 (recommandedd)
or you can use your package manager to install the
development versions of the wxWidgets packages which include the C++ headers.
The recommended way is to build wxWidgets from source, and use wxWidgets 3.0
or more recent (Older versions have a print function which does not work).
Verify that wx-config is in your path by running it from a command prompt.
Linux users then go to next step.

Note also wxWidgets must be compiled with the wxWebView support.
This is the default when building wxWidgets, but only if the libwebkitgtk-dev is installed
before building wxWidgets (sudo apt-get install libwebkitgtk-dev)

Install CMake
-------------
On windows, download the installation binary for windows from cmake.org.
Install that and choose to add cmake to your path during installation.  You
will have to restart your command shell for the new path to take effect.
Verify that cmake is in your path by trying to run it from a command prompt.


On linux, use your package manager to install cmake. You should get cmake 2.8.4
or later. If only an older one is available in your package repository, build
cmake from source. Verify that cmake is in your path by trying to run it from a
command prompt.


Obtain Sources
--------------
You can use the Launchpad repository or a tar file for this.  See the wiki.
To download files from  Launchpad repository, you should install bazaar (bzr) that is a
version control system like subversion, mercurial, git...

Launchpad repository handle 2 branches for KiCda sources:
- a product branch (used by developers, which is most of time usable in production)
- a stable branch (a copy of the testing branch,
        when the product branch is a stable state))
Remarks:
- The product branch is actively maintained
- From the product branch, you can go back to any previous version, using bzr features
- The stable branch is poorly or not maintained (and could be removed)

In order to have a working Kicad installtion, you need
- sources to build binaries
- libraries (they are not included in sources)
- documentation and translations (they are not included in sources)

product branch:
bzr branch https://code.launchpad.net/~kicad-product-committers/kicad kicad_src

Stable branch:
bzr branch https://code.launchpad.net/~kicad-product-committers/kicad/stable kicad_src

Components and Footprints libraries
all (schematic libs, 3D shapes ...) but new footprints libraries (use Download zip tool)
https://github.com/KiCad/kicad-library/

New footprints libraries (use Download zip tool for each lib you want)
https://github.com/KiCad/ for footprint libs (*.pretty folders)

A mirror of github is available, using bzr:
(schematic libs, 3D shapes ... all but new footprints libraries)
bzr checkout lp:~kicad-product-committers/kicad/library

Old legacy libraries:
bzr checkout lp:~dickelbeck/kicad/library-read-only

Note also Kicad is able to read on github.com/KiCad/ the *.pretty folders
without download, using github plugin.
(however the time to read them can be long)

Documentation and translations:
bzr branch lp:~kicad-developers/kicad/doc kicad_doc

Create Makefiles with CMake
---------------------------
On windows, go into your msys shell.
Linux and windows users both then make two "out of source" build directories:
    cd <kicadSource>
    mkdir -p build/release
    mkdir build/debug   (if you want a debug version of KiCad)
    cd build/release

On either cmake command line shown below, you can optionally include
    -DCMAKE_INSTALL_PREFIX=<finallInstallDir>
For instance on Linux: <finallInstallDir>=/usr/local/kicad or ~/kicad

On windows, run the following command:
    cmake -G "MSYS Makefiles" -DCMAKE_BUILD_TYPE=Release -DwxWidgets_ROOT_DIR=<wxInstallDir> ../../
Avoid installing Kicad on C: disk, which is protected by Windows.
Use D: or E: ...

On linux, run instead the following command:
    cmake -DCMAKE_BUILD_TYPE=Release ../../

Take a look at CMakeCache.txt, and in particular CMAKE_INSTALL_PREFIX, which
gives the final install directory. If not what you want, edit it with a text
editor and re-run the same cmake command again, but with no
-DCMAKE_INSTALL_PREFIX given on the command line.

Compiling with Make
------------------~
You compile Kicad here.  You will only need to do step 8) again when one of the
CMakeLists.txt files change.  If windows, you must be in your msys shell.
On either platform then:

    cd <kicadSource>/build/release
    make
    [sudo] make install

You are now done unless you want to make a Debug build.


Compiling a Debug version
-------------------------
    cd <kicadSource>/build/debug

On either cmake command line shown below, you can optionally include
-DCMAKE_INSTALL_PREFIX=<finallInstallDir> before the final ../../ argument.
Although normally you do not install the Debug binaries, you can debug them
where they were built.

On windows, run the following command:
    cmake -G "MSYS Makefiles" -DCMAKE_BUILD_TYPE=Debug -DwxWidgets_ROOT_DIR=<wxInstallDir> ../../
where <wxInstallDir> is <wxWidgets path>/Release

On linux, run instead the following command:
    cmake -DCMAKE_BUILD_TYPE=Debug -DwxWidgets_USE_DEBUG=ON ../../

Make the Debug binaries:
    make


See Documentation/compiling/build-config.txt for a list of all CMake options
available when compiling KiCad.