QGIS Coding and Compilation Guide
Total Page:16
File Type:pdf, Size:1020Kb
Quantum GIS Coding and Compilation Guide Version 1.4 'Enceladus' Preamble This document is the original Coding and Compilation Guide of the described software Quantum GIS. The software and hardware described in this document are in most cases registered trademarks and are therefore subject to the legal requirements. Quantum GIS is subject to the GNU General Public License. Find more information on the Quantum GIS Homepage http://qgis.osgeo.org. The details, data, results etc. in this document have been written and verified to the best of knowledge and responsibility of the authors and editors. Nevertheless, mistakes concerning the content are possible. Therefore, all data are not liable to any duties or guarantees. The authors, editors and publishers do not take any responsibility or liability for failures and their consequences. Your are always welcome to indicate possible mistakes. This document has been typeset with LATEX. It is available as LATEX source code via subversion and online as PDF document via http://qgis.osgeo.org/documentation/manuals.html. Translated versions of this document can be downloaded via the documentation area of the QGIS project as well. For more information about contributing to this document and about translating it, please visit: http://www.qgis.org/wiki/index.php/Community_Ressources Links in this Document This document contains internal and external links. Clicking on an internal link moves within the document, while clicking on an external link opens an internet address. In PDF form, internal links are shown in blue, while external links are shown in red and are handled by the system browser. In HTML form, the browser displays and handles both identically. Coding Compilation Guide Authors and Editors: Tim Sutton Marco Hugentobler Gary E. Sherman Tara Athan Godofredo Contreras Werner Macho Carson J.Q. Farmer Otto Dassau Jürgen E. Fischer Davis Wills Magnus Homann Martin Dobias With thanks to Tisham Dhar for preparing the initial msys (MS Windows) environment documentation, to Tom Elwertowski and William Kyngesburye for help in the MAC OSX Installation Section and to Carlos Dávila. If we have neglected to mention any contributors, please accept our apologies for this oversight. Copyright °c 2004 - 2009 Quantum GIS Development Team Internet: http://qgis.osgeo.org License of this document Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.3 or any later version published by the Free Software Foun- dation; with no Invariant Sections, no Front-Cover Texts and no Back-Cover Texts. A copy of the license is included in section 8 entitled "GNU Free Documentation License". QGIS 1.4 Installation and Coding Guide iii Contents Contents Title i Preamble ii Table of Contents iv 1 Writing a QGIS Plugin in C++ 1 1.1 Why C++ and what about licensing ............................. 1 1.2 Programming a QGIS C++ Plugin in four steps ...................... 1 1.3 Further information ...................................... 19 2 Creating C++ Applications 20 2.1 Creating a simple mapping widget ............................. 20 2.2 Working with QgsMapCanvas ................................ 23 3 Writing a QGIS Plugin in Python 27 3.1 Why Python and what about licensing ........................... 27 3.2 What needs to be installed to get started .......................... 27 3.3 Programming a simple PyQGIS Plugin in four steps ................... 28 3.4 Uploading the plugin to the repository ........................... 31 3.5 Further information ...................................... 32 4 Creating PyQGIS Applications 33 4.1 Designing the GUI ...................................... 33 4.2 Creating the MainWindow .................................. 34 4.3 Finishing Up ......................................... 39 4.4 Running the Application ................................... 40 5 Installation Guide 43 5.1 General Build Notes ..................................... 43 5.1.1 An overview of the dependencies required for building .............. 43 5.2 Building under windows using msys ............................ 43 5.2.1 MSYS: ......................................... 44 5.2.2 Qt4.3 ......................................... 44 5.2.3 Flex and Bison .................................... 45 5.2.4 Python stuff: (optional) ................................ 45 5.2.5 Subversion: ...................................... 46 5.2.6 CMake: ........................................ 46 5.2.7 QGIS: ......................................... 46 5.2.8 Compiling: ...................................... 46 5.2.9 Configuration ..................................... 47 5.2.10 Compilation and installation ............................. 47 QGIS 1.4 Installation and Coding Guide iv Contents 5.2.11 Create the installation package: (optional) ..................... 48 5.3 Building on Mac OSX using frameworks and cmake or Xcode .............. 48 5.3.1 Install Xcode ..................................... 48 5.3.2 Install Qt4 from .dmg ................................. 49 5.3.3 Install development frameworks for QGIS dependencies ............. 49 5.3.4 Install CMake for OSX ................................ 54 5.3.5 Install subversion for OSX .............................. 54 5.3.6 Check out QGIS from SVN ............................. 55 5.3.7 Configure the build .................................. 56 5.3.8 Building ........................................ 58 5.4 Building on GNU/Linux .................................... 59 5.4.1 Building QGIS with Qt4.x .............................. 59 5.4.2 Prepare apt ...................................... 59 5.4.3 Install Qt4 ....................................... 60 5.4.4 Install additional software dependencies required by QGIS ........... 60 5.4.5 GRASS Specific Steps ................................ 61 5.4.6 Setup ccache (Optional) ............................... 61 5.4.7 Prepare your development environment ...................... 61 5.4.8 Check out the QGIS Source Code ......................... 62 5.4.9 Starting the compile ................................. 62 5.4.10 Building Debian packages .............................. 63 5.4.11 Running QGIS .................................... 64 5.4.12 A practical case: Building QGIS and GRASS from source on Ubuntu with ECW and MrSID formats support ............................. 64 5.5 Creation of MSYS environment for compilation of Quantum GIS ............. 69 5.5.1 Initial setup ...................................... 69 5.5.2 Installing dependencies ............................... 70 5.5.3 Cleanup ........................................ 73 5.6 Building with MS Visual Studio ............................... 73 5.6.1 Setup Visual Studio ................................. 73 5.6.2 Download/Install Dependencies ........................... 74 5.6.3 Building QGIS with CMAKE ............................. 78 5.7 Building under Windows using MSVC Express ...................... 78 5.7.1 System preparation ................................. 79 5.7.2 Install the libraries archive .............................. 79 5.7.3 Install Visual Studio Express 2005 ......................... 79 5.7.4 Install Microsoft Platform SDK2 ........................... 80 5.7.5 Edit your vsvars ................................... 83 5.7.6 Environment Variables ................................ 84 5.7.7 Building Qt4.3.2 ................................... 85 5.7.8 Install Python ..................................... 86 5.7.9 Install SIP ....................................... 87 QGIS 1.4 Installation and Coding Guide v Contents 5.7.10 Install PyQt4 ..................................... 87 5.7.11 Install CMake ..................................... 87 5.7.12 Install Subversion .................................. 87 5.7.13 Initial SVN Check out ................................ 88 5.7.14 Create Makefiles using cmakesetup.exe ...................... 88 5.7.15 Running and packaging ............................... 89 6 QGIS Coding Standards 90 6.0.1 Classes ........................................ 90 6.0.2 Qt Designer ...................................... 91 6.0.3 C++ Files ....................................... 91 6.0.4 Variable Names ................................... 92 6.0.5 Enumerated Types .................................. 92 6.0.6 Global Constants ................................... 93 6.0.7 Editing ......................................... 93 6.0.8 API Compatibility ................................... 94 6.0.9 Coding Style ..................................... 94 6.1 SVN Access ......................................... 96 6.1.1 Accessing the Repository .............................. 96 6.1.2 Anonymous Access ................................. 97 6.1.3 QGIS documentation sources ............................ 97 6.1.4 SVN Documentation ................................. 97 6.1.5 Development in branches .............................. 98 6.1.6 Submitting Patches ................................. 99 6.1.7 Obtaining SVN Write Access ............................ 100 6.2 Unit Testing .......................................... 102 6.2.1 The QGIS testing framework - an overview .................... 102 6.2.2 Creating a unit test .................................. 103 6.2.3 Adding your unit test to CMakeLists.txt ....................... 109 6.2.4 The ADD_QGIS_TEST macro explained ...................... 109 6.2.5 Building your unit test ................................ 111 6.2.6 Run your tests .................................... 112 6.3 HIG (Human Interface