Merge pull request #4 from FOSSEE/develop

merging dev into master

1 files changed, 413 insertions, 0 deletions

diff --git a/Documentation/development/compiling.md b/Documentation/development/compiling.md
new file mode 100644
index 0000000..6a5ac92
--- /dev/null
+++ b/Documentation/development/compiling.md
@@ -0,0 +1,413 @@
+# Building KiCad from Source #
+If you are a user and not a developer, please consider using one of the prebuilt packages
+of KiCad which can be found at the [download][] page on the [KiCad website][].  Building KiCad
+from source is not for the faint of heart and is not recommended unless you have reasonable
+software development experience.  This document contains the instructions on how to build KiCad
+from source on the supported platforms.  It is not intended as a guide for installing or building
+[library dependencies](#library_dependencies).  Please consult you platforms documentation for
+installing packages or the source code when building the library dependencies.  Currently the
+supported platforms are Windows Versions 7-10, just about any version of Linux, and OSX
+10.7-10.10.  You may be able to build KiCad on other platforms but it is not supported.  On
+Windows and Linux the [GNU GCC][] is the only supported compiler and on OSX [Clang][] is the
+only supported compiler.
+
+[TOC]
+
+# Development Tools # {#development_tools}
+
+Before you begin building KiCad, there are a few tools required in addition to your compiler.
+Some of these tools are required to build from source and some are optional.
+
+## CMake Build Configuration Tool ## {#cmake}
+
+[CMake][] is the build configuration and makefile generation tool used by KiCad.  It is required.
+
+
+## Bazaar Version Control System ## {#bazaar}
+
+The official source code repository is hosted on [Launchpad][] and requires the [Bazaar][] version
+control system in order to create a branch of the latest source.  Bazaar is not required if you are
+going to build a stable version of KiCad from a source archive.
+
+## GIT Version Control System ## {#git}
+
+If you prefer to use [GIT][] for version control, there is a mirror of the official KiCad
+repository on [Github][].  GIT is not required if you are going to build a stable version of
+KiCad from a source archive.  Please note that the Github mirror is read only.  Do not submit
+pull requests to Github.  Changes should be sent to the KiCad developer's [mailing list][] as
+an attached patch with [PATCH] at the beginning of the subject.
+
+## Doxygen Code Documentation Generator ## {#doxygen_section}
+
+The KiCad source code is documented using [Doxygen][] which parses the KiCad source code files
+and builds a dependency tree along with the source documentation into HTML.  Doxygen is only
+required if you are going to build the KiCad documentation.
+
+## SWIG Simplified Wrapper and Interface Generator ## {#swig}
+
+[SWIG][] is used to generate the Python scripting language extensions for KiCad.  SWIG is not
+required if you are not going to build the KiCad scripting extension.
+
+
+# Library Dependencies # {#library_dependencies}
+
+This section includes a list of library dependencies required to build KiCad.  It does not
+include any dependencies of the libraries.  Please consult the library's documentation for any
+additional dependencies.  Some of these libraries are optional depending on you build
+configuration.  This is not a guide on how to install the library dependencies using you systems
+package management tools or how to build the library from source.  Consult the appropriate
+documentation to perform these tasks.
+
+## wxWidgets Cross Platform GUI Library## {#wxwidgets}
+
+[wxWidgets][] is the graphical user interface (GUI) library used by KiCad.  The current minimum
+version is 3.0.0.  However, 3.0.2 should be used whenever possible as there are some known bugs
+in prior versions that can cause problems on some platforms.  Please note that there are also
+some platform specific patches that must be applied before building wxWidgets from source.  These
+patches can be found in the [patches folder][] in the KiCad source.  These patches are named by
+the wxWidgets version and platform name they should be applied against.  wxWidgets must be built
+with the --with-opengl option.  If you installed the packaged version of wxWidgets on your system,
+verify that it was built with this option.
+
+## Boost C++ Libraries ## {#boost}
+
+The [Boost][] C++ library is required only if you intend to build KiCad with the system installed
+version of Boost instead of the default internally built version.  If you use the system installed
+version of Boost, version 1.56 or greater is required.  Please note there are some platform
+specific patches required to build a working Boost library.  These patches can be found in the
+[patches folder][] in the KiCad source.  These patches are named by the platform name they should
+be applied against.
+
+## GLEW OpenGL Extension Wrangler Library ## {#glew}
+
+The [OpenGL Extension Wrangler][GLEW] is an OpenGL helper library used by the KiCad graphics
+abstraction library [GAL] and is always required to build KiCad.
+
+## GLUT OpenGL Utility Toolkit Library ## {#glut}
+
+The [OpenGL Utility Toolkit][GLUT] is an OpenGL helper library used by the KiCad graphics
+abstraction library [GAL] and is always required to build KiCad.
+
+## Cairo 2D Graphics Library ## {#cairo}
+
+The [Cairo][] 2D graphics library is used as a fallback rendering canvas when OpenGL is no
+available and is always required to build KiCad.
+
+## Python Programming Language ## {#python}
+
+The [Python][] programming language is used to provide scripting support to KiCad.  It only needs
+to be install if the [KiCad scripting](#kicad_scripting) build configuration option is enabled.
+
+## wxPython Library ## {#wxpython}
+
+The [wxPython][] library is used to provide a scripting console for Pcbnew.  It only needs to be
+installed if the [wxPython scripting](#wxpython_scripting) build configuration option is enabled.
+When building KiCad with wxPython support, make sure the version of the wxWidgets library and
+the version of wxPython installed on your system are the same.  Mismatched versions have been
+known to cause runtime issues.
+
+# KiCad Build Configuration Options # {#build_opts}
+
+KiCad has many build options that can be configured to build different options depending on
+the availability of support for each option on a given platform.  This section documents
+these options and their default values.
+
+## Case Sensitivity ## {#case_sensitive_opt}
+
+The KICAD_KEEPCASE option allows you to build KiCad so that the string matching for component
+names is case sensitive of case insensitive.  This option is enabled by default.
+
+## Advanced Graphics Context ## {#graphics_context_opt}
+
+The USE_WX_GRAPHICS_CONTEXT option replaces wxDC with wxGraphicsContext for graphics rendering.
+This option is disabled by default.  Warning: the is experimental and has not been maintained
+so use at your own risk.
+
+## Graphics Context Overlay ## {#overlay_opt}
+
+The USE_WX_OVERLAY option is used to enable the optional wxOverlay class for graphics rendering
+on OSX.  This is enabled on OSX by default and disabled on all other platforms.
+
+## Scripting Support ## {#scripting_opt}
+
+The KICAD_SCRIPTING option is used to enable building the Python scripting support into Pcbnew.
+This options is disabled by default.
+
+## Scripting Module Support ## {#scripting_mod_opt}
+
+The KICAD_SCRIPTING_MODULES option is used to enable building and installing the Python modules
+supplied by KiCad.  This option is disabled by default.
+
+## wxPython Scripting Support ## {#wxpython_opt}
+
+The KICAD_SCRIPTING_WXPYTHON option is used to enable building the wxPython interface into
+Pcbnew including the wxPython console.  This option is disabled by default.
+
+## Github Plugin ## {#github_opt}
+
+The BUILD_GITHUB_PLUGIN option is used to control if the Github plugin is built.  This option is
+enabled by default.
+
+## Build with Static Libraries ## {#static_lib_opt}
+
+The KICAD_BUILD_STATIC option is used to build KiCad with static libraries.  This option is
+used for OSX builds only and is disabled by default.
+
+## Build with Dynamic Libraries ## {#dynamic_lib_opt}
+
+The KICAD_BUILD_DYNAMIC option is used to build KiCad with dynamic libraries.  This option is
+used for OSX only and is disabled by default.
+
+## Build with System Boost  ## {#boost_opt}
+
+The KICAD_SKIP_BOOST option allow you to use the Boost libraries installed on your system to
+be used instead of downloading Boost 1.54 and building a custom version specifically for
+building KiCad.  It is high recommended that you enable this option on Linux and use Boost
+version 1.56 or greater.  On other platforms you mileage may vary.  This option is disabled
+by default.
+
+## OSX Dependency Builder ## {#osx_deps_opt}
+
+The USE_OSX_DEPS_BUILDER option forces the build configuration to download and build the
+required dependencies to build KiCad on OSX.  This option is not longer maintained and most
+likely is broken.  Use it at your own peril.
+
+## Setting the Build Version and Repository Name ## {#build_version_opt}
+
+The KiCad version string is defined by the three CMake variables KICAD_VERSION, KICAD_BRANCH_NAME,
+and KICAD_VERSION_EXTRA.  Variables KICAD_BRANCH_NAME and KICAD_VERSION_EXTRA are defined as empty
+strings and can be set at configuration.  Unless the source branch is a stable release archive,
+KICAD_VERSION is set to "no-vcs-found".  If an optional variable is not define, it is not appended
+to the full version string.  If an optional variable is defined it is appended along with a leading
+'-' to the full version string as follows:
+
+    KICAD_VERSION[-KICAD_BRANCH_NAME][-KICAD_VERSION_EXTRA]
+
+When the version string is set to "no-vcs-found", the build script automatically creates the
+version string information from the [git][] repository information as follows:
+
+
+    (2016-08-26 revision 67230ac)-master
+     |                   |        |
+     |                   |        branch name, "HEAD" if not on a branch,
+     |                   |        or "unknown" if no .git present
+     |                   |
+     |                   abbreviated commit hash, or no-git if no .git
+     |                   present
+     |
+     date of commit, or date of build if no .git present
+
+# Getting the KiCad Source Code ## {#getting_src}
+
+There are several ways to get the KiCad source.  If you want to build the stable version you
+can down load the source archive from the [KiCad Launchpad][] developers page.  Use tar or some
+other archive program to extract the source on your system.  If you are using tar, use the
+following command:
+
+    tar -xzf kicad_src_archive.tar.gz
+
+If you are contributing directly to the KiCad project on Launchpad, you can create a local
+branch on your machine by using the following command:
+
+    bzr branch lp:repo_to_branch
+
+If you prefer to use [GIT][] as you version control system, you can clone the KiCad mirror on
+Github using the following command:
+
+    git clone https://github.com/KiCad/kicad-source-mirror
+
+Here is a list of source links:
+
+Stable release archive: https://launchpad.net/kicad/4.0/4.0.0-rc1/+download/kicad-4.0.0-rc1.tar.xz
+
+Development branch: https://code.launchpad.net/~kicad-product-committers/kicad/product
+
+Github mirror: https://github.com/KiCad/kicad-source-mirror
+
+# Building KiCad on Linux # {#build_linux}
+
+To perform a full build on Linux, run the following commands:
+
+    cd kicad_source_tree
+    mkdir -p build/release
+    mkdir build/debug               # Optional for debug build.
+    cd build/release
+    cmake -DCMAKE_BUILD_TYPE=Release \
+          -DKICAD_SCRIPTING=ON \
+          -DKICAD_SCRIPTING_MODULES=ON \
+          -DKICAD_SCRIPTING_WXPYTHON=ON \
+          ../../
+    make
+    sudo make install
+
+If the CMake configuration fails, determine the missing dependencies and install them on your
+system.  By default, CMake sets the install path on Linux to /usr/local.  Use the
+CMAKE_INSTALL_PREFIX option to specify a different install path.
+
+# Building KiCad on Windows # {#build_windows}
+
+The preferred Windows build environment is [MSYS2][].  The [MinGW][] build environment is still
+supported but it is not recommended because the developer is responsible for building *all* of
+the dependencies from source which is a huge and frustrating undertaking.  The [MSYS2][] project
+provides packages for all of the require dependencies to build KiCad.  To setup the [MSYS2][]
+build environment, depending on your system download and run either the [MSYS2 32-bit Installer][]
+or the [MSYS2 64-bit Installer][].  After the installer is finished, update to the latest
+package versions by running the `msys2_shell.bat` file located in the MSYS2 install path and
+running the command `pacman -Syu`.  If the msys2-runtime package is updated, close the shell
+and run `msys2_shell.bat`.
+
+## MSYS2 the Easy Way ## {#msys2_easy}
+
+The easiest way to build KiCad using the [MSYS2][] build environment is to use the KiCad
+[PKGBUILD][] provided by the MSYS2 project to build package using the head of the KiCad
+development branch.  To build the KiCad package, run the `msys2_shell.bat` file located in the
+MSYS2 install path and run the following commands:
+
+    pacman -S git
+    mkdir src
+    cd src
+    git clone https://github.com/Alexpux/MINGW-packages
+    cd MinGW-packages/mingw-w64-kicad-git
+    makepkg-mingw -is
+
+This will download and install all of the build dependencies, clone the KiCad source mirror
+from Github, create both 32-bit and 64-bit KiCad packages depending on your MSYS setup, and
+install the newly built KiCad packages.  Please note that this build process takes a very
+long time to build even on a fast system.
+
+## MSYS2 the Hard Way ## {#msys2_hard}
+
+If you do not want to create KiCad packages and prefer the traditional `make && make install`
+method of building KiCad, your task is significantly more involved.  For 64 bit builds run
+the `mingw64_shell.bat` file located in the MSYS2 install path.  At the command prompt run the
+the following commands:
+
+    pacman -S mingw-w64-x86_64-cmake \
+              mingw-w64-x86_64-doxygen \
+              mingw-w64-x86_64-gcc \
+              mingw-w64-x86_64-python2 \
+              mingw-w64-x86_64-pkg-config \
+              mingw-w64-x86_64-swig \
+              mingw-w64-x86_64-boost \
+              mingw-w64-x86_64-cairo \
+              mingw-w64-x86_64-glew \
+              mingw-w64-x86_64-curl \
+              mingw-w64-x86_64-wxPython \
+              mingw-w64-x86_64-wxWidgets
+    cd kicad-source
+    mkdir -p build/release
+    mkdir build/debug               # Optional for debug build.
+    cd build/release
+    cmake -DCMAKE_BUILD_TYPE=Release \
+          -G "MSYS Makefiles" \
+          -DCMAKE_PREFIX_PATH=/mingw64 \
+          -DCMAKE_INSTALL_PREFIX=/mingw64 \
+          -DDEFAULT_INSTALL_PATH=/mingw64 \
+          -DKICAD_SKIP_BOOST=ON \
+          -DKICAD_SCRIPTING=ON \
+          -DKICAD_SCRIPTING_MODULES=ON \
+          -DKICAD_SCRIPTING_WXPYTHON=ON \
+          ../../
+    make install
+
+# Building KiCad on OSX # {#build_osx}
+
+Building on OSX is challenging at best.  It typically requires building dependency libraries
+that require patching in order to work correctly.  For more information on the complexities of
+building KiCad on OSX, see the [OSX bundle build scripts][].
+
+Download the wxPython source and build using the following commands:
+
+    cd path-to-wxwidgets-src
+    patch -p0 < path-to-kicad-src/patches/wxwidgets-3.0.0_macosx.patch
+    patch -p0 < path-to-kicad-src/wxwidgets-3.0.0_macosx_bug_15908.patch
+    patch -p0 < path-to-kicad-src/patches/wxwidgets-3.0.0_macosx_soname.patch
+    patch -p0 < path-to-kicad-src/patches/wxwidgets-3.0.2_macosx_yosemite.patch
+    patch -p0 < path-to-kicad-src/patches/wxwidgets-3.0.0_macosx_scrolledwindow.patch
+    mkdir build
+    cd build
+    export MAC_OS_X_VERSION_MIN_REQUIRED=10.7
+    ../configure \
+        --prefix=`pwd`/../wx-bin \
+        --with-opengl \
+        --enable-aui \
+        --enable-utf8 \
+        --enable-html \
+        --enable-stl \
+        --with-libjpeg=builtin \
+        --with-libpng=builtin \
+        --with-regex=builtin \
+        --with-libtiff=builtin \
+        --with-zlib=builtin \
+        --with-expat=builtin \
+        --without-liblzma \
+        --with-macosx-version-min=10.7 \
+        --enable-universal-binary=i386,x86_64 \
+        CC=clang \
+        CXX=clang++
+
+Build KiCad using the following commands:
+
+    cd kicad-source
+    mkdir -p build/release
+    mkdir build/debug               # Optional for debug build.
+    cd build/release
+    cmake -DCMAKE_C_COMPILER=clang \
+          -DCMAKE_CXX_COMPILER=clang++ \
+          -DCMAKE_OSX_DEPLOYMENT_TARGET=10.7 \
+          -DwxWidgets_CONFIG_EXECUTABLE=path-to-wx-install/bin/wx-config \
+          -DKICAD_SCRIPTING=ON \
+          -DKICAD_SCRIPTING_MODULES=ON \
+          -DKICAD_SCRIPTING_WXPYTHON=ON \
+          -DPYTHON_EXECUTABLE=path-to-python-exe/python \
+          -DPYTHON_SITE_PACKAGE_PATH=wx/wx-bin/lib/python2.7/site-packages \
+          -DCMAKE_INSTALL_PREFIX=../bin \
+          -DCMAKE_BUILD_TYPE=Release \
+          ../../
+    make
+    make install
+
+# Known Issues # {#known_issues}
+
+There are some known issues that are platform and/or dependencie specific.  This section provides
+a list of the currently known issues when building KiCad.
+
+## Boost C++ Library Issues ## {#boost_issue}
+
+As of version 5 of [GNU GCC][], using the default configuration of downloading, patching, and
+building of Boost 1.54 will cause the KiCad build to fail.  Therefore a newer version of Boost
+must be used to build KiCad.  If your system has Boost 1.56 or greater installed, you job is
+straight forward.  Configure your KiCad build using `-DKICAD_SKIP_BOOST=ON`.  If your system
+does not have Boost 1.56 or greater installed, you will have to download and [build Boost][]
+from source.  If you are building Boost on windows using [MinGW][] you will have to apply the
+Boost patches in the KiCad source [patch folder][].
+
+
+[download]: http://kicad-pcb.org/download/
+[KiCad website]: http://kicad-pcb.org/
+[KiCad Launchpad]: https://launchpad.net/kicad
+[GNU GCC]: https://gcc.gnu.org/
+[Clang]: http://clang.llvm.org/
+[CMake]: https://cmake.org/
+[Launchpad]: https://code.launchpad.net/~kicad-product-committers/kicad/product
+[Bazaar]: http://bazaar.canonical.com/en/
+[GIT]: https://git-scm.com/
+[Github]: https://github.com/KiCad/kicad-source-mirror
+[Doxygen]: http://www.stack.nl/~dimitri/doxygen/
+[mailing list]: https://launchpad.net/~kicad-developers
+[SWIG]: http://www.swig.org/
+[wxWidgets]: http://wxwidgets.org/
+[patches folder]: http://bazaar.launchpad.net/~kicad-product-committers/kicad/product/files/head:/patches/
+[Boost]: http://www.boost.org/
+[GLEW]: http://glew.sourceforge.net/
+[GLUT]: https://www.opengl.org/resources/libraries/glut/
+[Cairo]: http://cairographics.org/
+[Python]: https://www.python.org/
+[wxPython]: http://wxpython.org/
+[MSYS2]: http://msys2.github.io/
+[MSYS2 32-bit Installer]: http://repo.msys2.org/distrib/i686/msys2-i686-20150916.exe
+[MSYS2 64-bit Installer]: http://repo.msys2.org/distrib/x86_64/msys2-x86_64-20150916.exe
+[PKGBUILD]: https://github.com/Alexpux/MINGW-packages/blob/master/mingw-w64-kicad-git/PKGBUILD
+[OSX bundle build scripts]:http://bazaar.launchpad.net/~adamwolf/+junk/kicad-mac-packaging/files
+[MinGW]: http://mingw.org/
+[build Boost]: http://www.boost.org/doc/libs/1_59_0/more/getting_started/index.html