Introduction
------------

This document details how to build KiCad from source on Windows. The current
supported method of building KiCad for Windows systems is to use the MinGW
compiler, either from Windows or cross compiling from Linux. MSYS can be
used on Windows to extend the range of subprojects that you can build, but
is not needed to build KiCad itself.

Visual Studio is not supported, and don't ask about it, it is not supported
and will not be, ever.

Install Build Tools
-------------------
This section describes the tools required to build KiCad from source and how
to install them.  Failure to install these tools properly will likely result
in build errors.

MinGW/MSYS
----------
MinGW/MSYS provides the compiler tools and a partial Posix environment useful
for building software.  Download the MinGW installer from http://mingw.org.
Run the installer and and verify MinGW and MSYS are checked.  You will also
need to expand the MinGW entry and select C++ from the list of supported
languages.  Only C is installed by default and C++ is required to build KiCad.

Bazaar
------
KiCad uses the Bazaar version control system to track source code changes.
The easiest way to get a copy of the KiCad source is to use Bazaar.  Bazaar
can be download from http://http://wiki.bazaar.canonical.com/WindowsDownloads.
Your best bet is to use the stand alone version of Bazaar rather than one of
the Python specific versions.

CMake
-----
The KiCad source uses CMake to make sure the system has the required software
and libraries installed to properly compile the source.  Download the latest
CMake installer from http://cmake.org.  Run the installer and make sure the
add CMake to PATH variable check box is checked.  If you fail to do this step,
the CMake executable will not be found.

Doxygen (Optional)
------------------
Doxygen is used to generate HTML documentation of the KiCad source code.  While
it is not necessary to install Doxygen, it is a very good way to learn your way
around the KiCad code base.  It is highly recommended for new developers.  The
latest Doxygen installer can be downloaded from http://www.stack.nl/~dimitri/
doxygen/

Python (Optional)
-----------------
KiCad supports the Python scripting language (currently only Pcbnew scripting
exists).  Currently the Python scripting support will only build against the
version 2 branch of Python.  The Python installer can be downloaded from http://
www.python.org.

SWIG (Optional)
---------------
SWIG is used to generate the Python scripting code.  It must be installed to
build the Python scripting support.  Unfortunately there in no installer for
windows.  You can download precompiled binaries from http://http://www.swig.
org/download.html and install swig.exe.  Make sure the folder you install the
SWIG binary into is in the system PATH.  Otherwise CMake will not be able to
find it.

NullSoft Installer System (Optional)
------------------------------------
The NullSoft Installer System (NSIS) is used to create a Windows installer for
end users from the binaries created from the KiCad source along with the
library and documentation files.  NSIS is typically only used be developers who
create installers for end users and is not required if you install from source.
NSIS can be downloaded from http://nsis.sourceforge.net/Download.


Install and Build Libraries
---------------------------
This section documents installing and build all of the software libraries
required to build KiCad.  As of now, these libraries have to be built because
MinGW builds of these libraries are not readily available  Attempting to link
programs built on MinGW with libraries from other compilers (namely Microsoft
Visual C) is problematic.  It can be done but it is not painless.  As far as
the author of this document knows, MinGW can only link to Visual Studio C
libraries.  The name mangling of Visual Studio C++ is not compatible with the
MinGW linker.

Build and Install the wxWidgets Library
---------------------------------------
The wxWidgets library is the base that KiCad is built upon.  Version 2.9.4
or later of wxWidgets should be used on Windows.  You may be able to build
KiCad with older versions of wxWidgets but it is not recommended.  wxWidgets
can be downloaded from http://http://www.wxwidgets.org/downloads/


Unzip the wxWidgets zip file into your preferred build directory.  Avoid using
spaces in the path names.  Some MinGW tools do not play well with them.  It is
always best to error on the side of caution.

Open MinGW and change to the wxWidgets source directory.  If you don't want to
install the wxWidgets library into MinGW then enter the following commands:

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

If you want to install wxWidgets in MinGW then enter the following commands:
#mkdir Release
#cd Release
#../configure --prefix=/mingw --with-opengl
#make && make install
#move /mingw/lib/wxmsw*.dll /mingw/bin

The last command is critical so that the libraries are in the MinGW PATH
and can be found at run time.  If you want to build a full debugging version
of wxWidgets, add --enable-debug to the configure command.  If you are going
to use the GNU debugger, you may also want to build the debugging libraries
with the extra GDB debugging information by adding --enable-debug_gdb to the
configure command.

Download the KiCad Source Code
------------------------------
You can use the Launchpad repository or a tar file for this.  See the wiki.
To download files from  Launchpad repository, you need to install the Bazaar
(bzr) version control system.

Launchpad repository has two branches for KiCad sources:
- a testing branch (used by developers)
- a stable branch (a copy of the testing branch, when this testing branch is
  near a stable state)

To download the testing branch:
#bzr branch lp:kicad kicad_testing

To download the stable branch:
#bzr branch lp:kicad/stable kicad_stable

To download the component and footprint libraries
#bzr branch lp:~kicad-lib-committers/kicad/library kicad_libraries

To download the documentation and translation files:
#bzr branch lp:~kicad-developers/kicad/doc kicad_doc

Create Makefiles with CMake
---------------------------
Open your Msys shell.  Create two "out of source" build directories at the
command line enter the following commands:

#cd <kicadSource>
#mkdir -p build/release         # Build path can be anywhere you prefer.
#mkdir build/debug              # Only if you want a debug version of KiCad.

To create a release build of KiCad, run the following command:
#cd build
#cmake -G "MSYS Makefiles"                  \  # Back slashes are not required
       -DCMAKE_BUILD_TYPE=Release           \  # and are for formatting only.
       -DKICAD_TESTING_VERSION=ON ../../

If the configuration fails, you have failed to install the required software
on you system.  The error message should give you a good indication of what is
missing.  You must resolve this before you can build KiCad.

Compiling the Code
------------------
To build KiCad, at the command line enter following comnands:

#cd <kicadSource>/build/release
#make

Installing KiCad
----------------
To install Kicad, at the command line enter the following commands:

#cd <kicadSource>/build/release
#make install

If you get any errors during the installation, you probably do not have the
appropriate privileges to the install path.  Take a look at CMakeCache.txt
that was created when you ran CMake, and in particular look at the value of
the CMAKE_INSTALL_PREFIX variable.  This is where KiCad will be installed.  If
this not where you want KiCad installed, edit it with a text editor rerun the
make install command.  You do not have the appropriate privileges to install
KiCad in the CMAKE_INSTALL_PATH, run the make install command as administrator.

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


Compiling a Debug version
-------------------------
To create a debug version of KiCad, enter the following commands:

#cd <kicadSource>/build/debug
#cmake -G "MSYS Makefiles"                       \
       -DCMAKE_BUILD_TYPE=Debug                  \
       -DKICAD_TESTING_VERSION=ON ../../
#make

Generally speaking you do not install debug binaries.  They can be debugged in
place.  To monitor the debugging output, you can download the Windows debug
viewer DbgView from http://technet.microsoft.com/en-us/sysinternals/
bb896647.aspx

Compiling the Python Scripting Support.
---------------------------------------

Before building KiCad Python scripting extension, you must create a MinGW
compatible Python link library.  The directions to do this can be found in
the "How do I create Python extensions?" FAQ at http://www.mingw.org/wiki/FAQ.

To build KiCad with Python scripting support, run CMake as follows and then
compile the source as described above.

#cmake -G "MSYS Makefiles"                       \
       -DCMAKE_BUILD_TYPE=Release                \
       -DKICAD_PYTHON_SCRIPTING=ON               \
       -DKICAD_PYTHON_MODULES=ON                 \
       -DKICAD_TESTING_VERSION=ON ../../

You only need to include the KICAD_PYTHON_MODULES option if you want to
install the python modules that ship with KiCad.  Also note that the wxPython
support cannot be compiled on Windows at this time due to library conflicts
between MinGW and Python.  Work is currently underway by the KiCad developers
to provide a MinGW build of Python which should resolve this issue.

Building the Developer Documentation
------------------------------------
To build the HTML developer documentation, run the following commands:

#cd <kicadSource>/build/debug
#make doxygen-docs

The documentation will be created in the <kicadSouce>/Documenation/html
directory.
