diff --git a/CODING b/CODING index da51fa91cfe..f99320c9429 100644 --- a/CODING +++ b/CODING @@ -16,7 +16,7 @@ Developers guide for QGIS 1.3. C++ Files 1.3.1. Names 1.3.2. Standard Header and License - 1.3.3. CVS Keyword + 1.3.3. SVN Keyword 1.4. Variable Names 1.5. Enumerated Types 1.6. Global Constants @@ -36,7 +36,7 @@ Developers guide for QGIS 2.1. Accessing the Repository 2.2. Anonymous Access 2.3. QGIS documentation sources - 2.4. Documentation + 2.4. SVN Documentation 2.5. Development in branches 2.5.1. Purpose 2.5.2. Procedure @@ -69,104 +69,118 @@ Developers guide for QGIS These standards should be followed by all QGIS developers. - 1.1. Classes - ============ + 1.1. Classes + ============ - 1.1.1. Names - ============ + 1.1.1. Names + ============ Class in QGIS begin with Qgs and are formed using mixed case. Examples: - QgsPoint - QgsMapCanvas - QgsRasterLayer + QgsPoint + QgsMapCanvas + QgsRasterLayer - 1.1.2. Members - ============== + 1.1.2. Members + ============== -Class member names begin with a lower case m and are formed using mixed case. +Class member names begin with a lower case m and are formed using mixed +case. - mMapCanvas - mCurrentExtent + mMapCanvas + mCurrentExtent All class members should be private. Public class members are STRONGLY discouraged - 1.1.3. Accessor Functions - ========================= + 1.1.3. Accessor Functions + ========================= -Class member values should be obtained through accesssor functions. The function should be named without a get prefix. Accessor functions for the two private members above would be: +Class member values should be obtained through accesssor functions. The +function should be named without a get prefix. Accessor functions for the +two private members above would be: - mapCanvas() - currentExtent() + mapCanvas() + currentExtent() - 1.1.4. Functions - ================ + 1.1.4. Functions + ================ -Function names begin with a lowercase letter and are formed using mixed case. The function name should convey something about the purpose of the function. +Function names begin with a lowercase letter and are formed using mixed case. +The function name should convey something about the purpose of the function. - updateMapExtent() - setUserOptions() + updateMapExtent() + setUserOptions() - 1.2. Qt Designer - ================ + 1.2. Qt Designer + ================ - 1.2.1. Generated Classes - ======================== + 1.2.1. Generated Classes + ======================== -QGIS classes that are generated from Qt Designer (ui) files should have a Base suffix. This identifies the class as a generated base class. +QGIS classes that are generated from Qt Designer (ui) files should have a +Base suffix. This identifies the class as a generated base class. Examples: - QgsPluginMangerBase - QgsUserOptionsBase + QgsPluginMangerBase + QgsUserOptionsBase - 1.2.2. Dialogs - ============== + 1.2.2. Dialogs + ============== All dialogs should implement the following: * Tooltip help for all toolbar icons and other relevant widgets * WhatsThis help for all widgets on the dialog - * An optional (though highly recommended) context sensitive Help button that directs the user to the appropriate help page by launching their web browser + * An optional (though highly recommended) context sensitive Help button + that directs the user to the appropriate help page by launching their web + browser - 1.3. C++ Files - ============== + 1.3. C++ Files + ============== - 1.3.1. Names - ============ + 1.3.1. Names + ============ -C++ implementation and header files should be have a .cpp and .h extension respectively. -Filename should be all lowercase and, in the case of classes, match the class name. +C++ implementation and header files should be have a .cpp and .h extension +respectively. Filename should be all lowercase and, in the case of classes, +match the class name. Example: - Class QgsFeatureAttribute source files are - qgsfeatureattribute.cpp and qgsfeatureattribute.h + Class QgsFeatureAttribute source files are + qgsfeatureattribute.cpp and qgsfeatureattribute.h +/!\ Note: in case it is not clear from the statement above, for a filename +to match a class name it implicitly means that each class should be declared +and implemented in its own file. This makes it much easier for newcomers to +identify where the code is relating to specific class. - 1.3.2. Standard Header and License - ================================== -Each source file should contain a header section patterned after the following example: + 1.3.2. Standard Header and License + ================================== + +Each source file should contain a header section patterned after the following +example: /*************************************************************************** @@ -186,31 +200,35 @@ Each source file should contain a header section patterned after the following e - 1.3.3. CVS Keyword - ================== + 1.3.3. SVN Keyword + ================== -Each source file should contain the $Id$ keyword. This will be expanded by CVS to contain useful information about the file, revision, last committer, and date/time of last checkin. +Each source file should contain the $Id$ keyword. This will be expanded by CVS +to contain useful information about the file, revision, last committer, and +date/time of last checkin. -Place the keyword right after the standard header/license that is found at the top of each source file: +Place the keyword right after the standard header/license that is found at the +top of each source file: - /* $Id$ */ + /* $Id$ */ - 1.4. Variable Names - =================== + 1.4. Variable Names + =================== Variable names begin with a lower case letter and are formed using mixed case. Examples: - mapCanvas - currentExtent + mapCanvas + currentExtent - 1.5. Enumerated Types - ===================== + + 1.5. Enumerated Types + ===================== Enumerated types should be named in CamelCase with a leading capital e.g.: @@ -224,12 +242,12 @@ Enumerated types should be named in CamelCase with a leading capital e.g.: } ; -Do not use generic type names that will conflict with other types. e.g. use "UnkownUnit" rather -than "Unknown" +Do not use generic type names that will conflict with other types. e.g. use +"UnkownUnit" rather than "Unknown" - 1.6. Global Constants - ===================== + 1.6. Global Constants + ===================== Global constants should be written in upper case underscore separated e.g.: @@ -238,44 +256,49 @@ Global constants should be written in upper case underscore separated e.g.: - 1.7. Editing - ============ + 1.7. Editing + ============ -Any text editor/IDE can be used to edit QGIS code, providing the following requirements are met. +Any text editor/IDE can be used to edit QGIS code, providing the following +requirements are met. - 1.7.1. Tabs - =========== + 1.7.1. Tabs + =========== -Set your editor to emulate tabs with spaces. Tab spacing should be set to 2 spaces. +Set your editor to emulate tabs with spaces. Tab spacing should be set to 2 +spaces. - 1.7.2. Indentation - ================== + 1.7.2. Indentation + ================== -Source code should be indented to improve readability. There is a .indent.pro file in the QGIS src directory that contains the switches to be used when indenting code using the GNU indent program. If you don't use GNU indent, you should emulate these settings. +Source code should be indented to improve readability. There is a .indent.pro +file in the QGIS src directory that contains the switches to be used when +indenting code using the GNU indent program. If you don't use GNU indent, you +should emulate these settings. - 1.7.3. Braces - ============= + 1.7.3. Braces + ============= Braces should start on the line following the expression: - if(foo == 1) - { - // do stuff - ... - }else - { - // do something else - ... - } + if(foo == 1) + { + // do stuff + ... + }else + { + // do something else + ... + } - 1.8. API Compatibility - ====================== + 1.8. API Compatibility + ====================== From QGIS 1.0 we will provide a stable, backwards compatible API. This will provide a stable basis for people to develop against, knowing their code will @@ -302,29 +325,30 @@ Trolltech developers e.g. - 1.9. Coding Style - ================= + 1.9. Coding Style + ================= -Here are described some programming hints and tips that will hopefully reduce errors, development time, and maintenance. +Here are described some programming hints and tips that will hopefully reduce +errors, development time, and maintenance. - 1.9.1. Where-ever Possible Generalize Code - ========================================== + 1.9.1. Where-ever Possible Generalize Code + ========================================== - If you are cut-n-pasting code, or otherwise writing the same thing more than once, consider consolidating the code - into a single function. + If you are cut-n-pasting code, or otherwise writing the same thing more than + once, consider consolidating the code into a single function. This will: * allow changes to be made in one location instead of in multiple places * help prevent code bloat - * make it more difficult for multiple copies to evolve differences over time, thus making it harder to understand and -maintain for others + * make it more difficult for multiple copies to evolve differences over time, + thus making it harder to understand and maintain for others - 1.9.2. Prefer Having Constants First in Predicates - ================================================== + 1.9.2. Prefer Having Constants First in Predicates + ================================================== Prefer to put constants first in predicates. @@ -332,15 +356,17 @@ Prefer to put constants first in predicates. "0 == value" instead of "value == 0" -This will help prevent programmers from accidentally using "=" when they meant to use "==", which can introduce very subtle -logic bugs. The compiler will generate an error if you accidentally use "=" instead of "==" for comparisons since constants -inherently cannot be assigned values. +This will help prevent programmers from accidentally using "=" when they meant +to use "==", which can introduce very subtle logic bugs. The compiler will +generate an error if you accidentally use "=" instead of "==" for comparisons +since constants inherently cannot be assigned values. - 1.9.3. Whitespace Can Be Your Friend - ==================================== + 1.9.3. Whitespace Can Be Your Friend + ==================================== -Adding spaces between operators, statements, and functions makes it easier for humans to parse code. +Adding spaces between operators, statements, and functions makes it easier for +humans to parse code. Which is easier to read, this: @@ -355,31 +381,35 @@ or this: - 1.9.4. Add Trailing Identifying Comments - ======================================== + 1.9.4. Add Trailing Identifying Comments + ======================================== -Adding comments at the end of function, struct and class implementations makes it easier to find them later. +Adding comments at the end of function, struct and class implementations makes +it easier to find them later. -Consider that you're at the bottom of a source file and need to find a very long function -- without these kinds of trailing -comments you will have to page up past the body of the function to find its name. Of course this is ok if you wanted to find -the beginning of the function; but what if you were interested at code near its end? You'd have to page up and then back down -again to the desired part. +Consider that you're at the bottom of a source file and need to find a very +long function -- without these kinds of trailing comments you will have to page +up past the body of the function to find its name. Of course this is ok if you +wanted to find the beginning of the function; but what if you were interested +at code near its end? You'd have to page up and then back down again to the +desired part. -E.g., +e.g., void foo::bar() { // ... imagine a lot of code here - } // foo::bar() + } // foo::bar() - 1.9.5. Use Braces Even for Single Line Statements - ================================================= + 1.9.5. Use Braces Even for Single Line Statements + ================================================= -Using braces for code in if/then blocks or similar code structures even for single line statements means that adding another -statement is less likely to generate broken code. +Using braces for code in if/then blocks or similar code structures even for +single line statements means that adding another statement is less likely to +generate broken code. Consider: @@ -390,8 +420,9 @@ Consider: baz(); -Adding code after bar() or baz() without adding enclosing braces would create broken code. Though most programmers would -naturally do that, some may forget to do so in haste. +Adding code after bar() or baz() without adding enclosing braces would create +broken code. Though most programmers would naturally do that, some may forget +to do so in haste. So, prefer this: @@ -407,13 +438,14 @@ So, prefer this: - 1.9.6. Book recommendations - =========================== + 1.9.6. Book recommendations + =========================== + +- Effective C++ (http://www.awprofessional.com/title/0321334876), Scott Meyers +- More Effective C++ (http://www.awprofessional.com/bookstore/product.asp?isbn=020163371X&rl=1), Scott Meyers +- Effective STL (http://www.awprofessional.com/title/0201749629), Scott Meyers +- Design Patterns (http://www.awprofessional.com/title/0201634988), GoF - * Effective C++ (http://www.awprofessional.com/title/0321334876), Scott Meyers - * More Effective C++ (http://www.awprofessional.com/bookstore/product.asp?isbn=020163371X&rl=1), Scott Meyers - * Effective STL (http://www.awprofessional.com/title/0201749629), Scott Meyers - * Design Patterns (http://www.awprofessional.com/title/0201634988), GoF You should also really read this article from Qt Quarterly on http://doc.trolltech.com/qq/qq13-apis.html designing Qt style (APIs) @@ -425,8 +457,8 @@ http://doc.trolltech.com/qq/qq13-apis.html designing Qt style (APIs) This page describes how to get started using the QGIS Subversion repository - 2.1. Accessing the Repository - ============================= + 2.1. Accessing the Repository + ============================= To check out QGIS HEAD: @@ -435,38 +467,44 @@ To check out QGIS HEAD: - 2.2. Anonymous Access - ===================== + 2.2. Anonymous Access + ===================== -You can use the following commands to perform an anonymous checkout from the QGIS Subversion repository. -Note we recommend checking out the trunk (unless you are a developer or really HAVE to have the latest -changes and dont mind lots of crashing!). +You can use the following commands to perform an anonymous checkout from the +QGIS Subversion repository. Note we recommend checking out the trunk (unless +you are a developer or really HAVE to have the latest changes and dont mind +lots of crashing!). -You must have a subversion client installed prior to checking out the code. See the Subversion website -for more information. The Links page contains a good selection of SVN clients for various platforms. +You must have a subversion client installed prior to checking out the code. See +the Subversion website for more information. The Links page contains a good +selection of SVN clients for various platforms. To check out a branch svn co https://svn.osgeo.org/qgis/branches/ + To check out SVN stable trunk: svn co https://svn.osgeo.org/qgis/trunk/qgis qgis_trunk -/!\ Note: If you are behind a proxy server, edit your ~/subversion/servers file to specify -your proxy settings first! +/!\ Note: If you are behind a proxy server, edit your ~/subversion/servers +file to specify your proxy settings first! -/!\ Note: In QGIS we keep our most stable code in trunk. Periodically we will tag a release -off trunk, and then continue stabilisation and selective incorporation of new features into trunk. +/!\ Note: In QGIS we keep our most stable code in the version 1_0 branch. +Trunk contains code for the so called 'unstable' release series. Periodically +we will tag a release off trunk, and then continue stabilisation and selective +incorporation of new features into trunk. -See the INSTALL file in the source tree for specific instructions on building development versions. +See the INSTALL file in the source tree for specific instructions on building +development versions. - 2.3. QGIS documentation sources - =============================== + 2.3. QGIS documentation sources + =============================== If you're interested in checking out Quantum GIS documentation sources: @@ -477,58 +515,73 @@ If you're interested in checking out Quantum GIS documentation sources: You can also take a look at DocumentationWritersCorner for more information. - 2.4. Documentation - ================== + 2.4. SVN Documentation + ====================== The repository is organized as follows: http://wiki.qgis.org/images/repo.png -See the Subversion book http://svnbook.red-bean.com for information on becoming a SVN master. +See the Subversion book http://svnbook.red-bean.com for information on becoming +a SVN master. - 2.5. Development in branches - ============================ + 2.5. Development in branches + ============================ - 2.5.1. Purpose - ============== + 2.5.1. Purpose + ============== -The complexity of the QGIS source code has increased considerably during the last years. Therefore it is hard -to anticipate the side effects that the addition of a feature will have. In the past, the QGIS project had very -long release cycles because it was a lot of work to reetablish the stability of the software system after new -features were added. To overcome these problems, QGIS switched to a development model where new features are -coded in svn branches first and merged to trunk (the main branch) when they are finished and stable. This section -describes the procedure for branching and merging in the QGIS project. +The complexity of the QGIS source code has increased considerably during the +last years. Therefore it is hard to anticipate the side effects that the +addition of a feature will have. In the past, the QGIS project had very long +release cycles because it was a lot of work to reetablish the stability of the +software system after new features were added. To overcome these problems, QGIS +switched to a development model where new features are coded in svn branches +first and merged to trunk (the main branch) when they are finished and stable. +This section describes the procedure for branching and merging in the QGIS +project. - 2.5.2. Procedure - ================ + 2.5.2. Procedure + ================ - * Initial announcement on mailing list -Before starting, make an announcement on the developer mailing list to see if another developer is -already working on the same feature. Also contact the technical advisor of the project steering committee -(PSC). If the new feature requires any changes to the QGIS architecture, a request for comment (RFC) is needed. - * Create a branch -Create a new svn branch for the development of the new feature (see UsingSubversion for the svn syntax). Now -you can start developing. - * Merge from trunk regularly -It is recommended to merge the changes in trunk to the branch on a regular basis. This makes it easier to merge -the branch back to trunk later. - * Documentation on wiki -It is also recommended to document the intended changes and the current status of the work on a wiki page. - * Testing before merging back to trunk -When you are finished with the new feature and happy with the stability, make an announcement on the developer list. -Before merging back, the changes will be tested by developers and users. Binary packages (especially for OsX and Windows) -will be generated to also involve non-developers. In trac, a new Component will be opened to file tickets against. -Once there are no remaining issues left, the technical advisor of the PSC merges the changes into trunk. +- Initial announcement on mailing list: +Before starting, make an announcement on the developer mailing list to see if +another developer is already working on the same feature. Also contact the +technical advisor of the project steering committee (PSC). If the new feature +requires any changes to the QGIS architecture, a request for comment (RFC) is +needed. + +- Create a branch: +Create a new svn branch for the development of the new feature (see +UsingSubversion for the svn syntax). Now you can start developing. + +- Merge from trunk regularly: +It is recommended to merge the changes in trunk to the branch on a regular +basis. This makes it easier to merge the branch back to trunk later. + +- Documentation on wiki: +It is also recommended to document the intended changes and the current status +of the work on a wiki page. + +- Testing before merging back to trunk: +When you are finished with the new feature and happy with the stability, make +an announcement on the developer list. Before merging back, the changes will +be tested by developers and users. Binary packages (especially for OsX and +Windows) will be generated to also involve non-developers. In trac, a new +Component will be opened to file tickets against. Once there are no remaining +issues left, the technical advisor of the PSC merges the changes into trunk. - 2.5.3. Creating a branch - ======================== -We prefer that new feature developments happen out of trunk so that trunk remains in a -stable state. To create a branch use the following command: + + 2.5.3. Creating a branch + ======================== + +We prefer that new feature developments happen out of trunk so that trunk +remains in a stable state. To create a branch use the following command: svn copy https://svn.osgeo.org/qgis/trunk/qgis https://svn.osgeo.org/qgis/branches/qgis_newfeature @@ -536,12 +589,13 @@ stable state. To create a branch use the following command: - 2.5.4. Merge regularly from trunk to branch - =========================================== + 2.5.4. Merge regularly from trunk to branch + =========================================== -When working in a branch you should regularly merge trunk into it so that your branch does not diverge more -than necessary. In the top level dir of your branch, first type `svn info` to determine the revision -numbers of your branch which will produce output something like this: +When working in a branch you should regularly merge trunk into it so that your +branch does not diverge more than necessary. In the top level dir of your +branch, first type `svn info` to determine the revision numbers of your +branch which will produce output something like this: timlinux@timlinux-desktop:~/dev/cpp/qgis_raster_transparency_branch$ svn info @@ -558,14 +612,16 @@ numbers of your branch which will produce output something like this: Propriedades da Última Mudança: 2007-01-09 11:32:55 -0200 (Ter, 09 Jan 2007) -The second revision number shows the revision number of the start revision of your branch and the first the -current revision. You can do a dry run of the merge like this: +The second revision number shows the revision number of the start revision of +your branch and the first the current revision. You can do a dry run of the +merge like this: svn merge --dry-run -r 6495:6546 https://svn.osgeo.org/qgis/trunk/qgis -After you are happy with the changes that will be made do the merge for real like this: +After you are happy with the changes that will be made do the merge for real +like this: svn merge -r 6495:6546 https://svn.osgeo.org/qgis/trunk/qgis @@ -573,30 +629,33 @@ After you are happy with the changes that will be made do the merge for real lik - 2.6. Submitting Patches - ======================= + 2.6. Submitting Patches + ======================= -There are a few guidelines that will help you to get your patches into QGIS easily, and help us -deal with the patches that are sent to use easily. +There are a few guidelines that will help you to get your patches into QGIS +easily, and help us deal with the patches that are sent to use easily. - 2.6.1. Patch file naming - ======================== + 2.6.1. Patch file naming + ======================== -If the patch is a fix for a specific bug, please name the file with the bug number in it e.g. -bug777fix.diff, and attach it to the original bug report in trac (https://trac.osgeo.org/qgis/). +If the patch is a fix for a specific bug, please name the file with the bug +number in it e.g. bug777fix.diff, and attach it to the original bug report +in trac (https://trac.osgeo.org/qgis/). -If the bug is an enhancement or new feature, its usually a good idea to create a ticket in -trac (https://trac.osgeo.org/qgis/) first and then attach you +If the bug is an enhancement or new feature, its usually a good idea to create +a ticket in trac (https://trac.osgeo.org/qgis/) first and then attach you - 2.6.2. Create your patch in the top level QGIS source dir - ========================================================= + 2.6.2. Create your patch in the top level QGIS source dir + ========================================================= -This makes it easier for us to apply the patches since we don't need to navigate to a specific -place in the source tree to apply the patch. Also when I receive patches I usually evaluate them -using kompare, and having the patch from the top level dir makes this much easier. Below is an -example of you you can include multiple changed files into your patch from the top level directory: +This makes it easier for us to apply the patches since we don't need to +navigate to a specific place in the source tree to apply the patch. Also when I +receive patches I usually evaluate them using kompare, and having the patch +from the top level dir makes this much easier. Below is an example of you you +can include multiple changed files into your patch from the top level +directory: cd qgis @@ -604,11 +663,12 @@ example of you you can include multiple changed files into your patch from the t - 2.6.3. Including non version controlled files in your patch - =========================================================== + 2.6.3. Including non version controlled files in your patch + =========================================================== -If your improvements include new files that don't yet exist in the repository, you should indicate -to svn that they need to be added before generating your patch e.g. +If your improvements include new files that don't yet exist in the repository, +you should indicate to svn that they need to be added before generating your +patch e.g. cd qgis @@ -617,37 +677,44 @@ to svn that they need to be added before generating your patch e.g. - 2.6.4. Getting your patch noticed - ================================= + 2.6.4. Getting your patch noticed + ================================= -QGIS developers are busy folk. We do scan the incoming patches on bug reports but sometimes we miss things. -Don't be offended or alarmed. Try to identify a developer to help you - using the ["Project Organigram"] and -contact them asking them if they can look at your patch. If you dont get any response, you can escalate your -query to one of the Project Steering Committee members (contact details also available on the ["Project Organigram"]). +QGIS developers are busy folk. We do scan the incoming patches on bug reports +but sometimes we miss things. Don't be offended or alarmed. Try to identify a +developer to help you - using the ["Project Organigram"] and contact them +asking them if they can look at your patch. If you dont get any response, you +can escalate your query to one of the Project Steering Committee members +(contact details also available on the ["Project Organigram"]). - 2.6.5. Due Diligence - ==================== + 2.6.5. Due Diligence + ==================== -QGIS is licensed under the GPL. You should make every effort to ensure you only submit patches which are -unencumbered by conflicting intellectual property rights. Also do not submit code that you are not happy to -have made available under the GPL. +QGIS is licensed under the GPL. You should make every effort to ensure you only +submit patches which are unencumbered by conflicting intellectual property +rights. Also do not submit code that you are not happy to have made available +under the GPL. - 2.7. Obtaining SVN Write Access - =============================== + 2.7. Obtaining SVN Write Access + =============================== -Write access to QGIS source tree is by invitation. Typically when a person submits several (there is no fixed -number here) substantial patches that demonstrate basic competance and understanding of C++ and QGIS coding -conventions, one of the PSC members or other existing developers can nominate that person to the PSC for granting -of write access. The nominator should give a basic promotional paragraph of why they think that person should gain -write access. In some cases we will grant write access to non C++ developers e.g. for translators and documentors. -In these cases, the person should still have demonstrated ability to submit patches and should ideally have submtted -several substantial patches that demonstrate their understanding of modifying the code base without breaking things, etc. +Write access to QGIS source tree is by invitation. Typically when a person +submits several (there is no fixed number here) substantial patches that +demonstrate basic competance and understanding of C++ and QGIS coding +conventions, one of the PSC members or other existing developers can nominate +that person to the PSC for granting of write access. The nominator should give +a basic promotional paragraph of why they think that person should gain write +access. In some cases we will grant write access to non C++ developers e.g. for +translators and documentors. In these cases, the person should still have +demonstrated ability to submit patches and should ideally have submtted several +substantial patches that demonstrate their understanding of modifying the code +base without breaking things, etc. - 2.7.1. Procedure once you have access - ===================================== + 2.7.1. Procedure once you have access + ===================================== Checkout the sources: @@ -671,18 +738,20 @@ Make your edits cd .. -Make your changes in sources. Always check that everything compiles before making any commits. -Try to be aware of possible breakages your commits may cause for people building on other -platforms and with older / newer versions of libraries. +Make your changes in sources. Always check that everything compiles before +making any commits. Try to be aware of possible breakages your commits may +cause for people building on other platforms and with older / newer versions of +libraries. -Add files (if you added any new files). The svn status command can be used to quickly see -if you have added new files. +Add files (if you added any new files). The svn status command can be used to +quickly see if you have added new files. svn status src/pluguns/grass/modules -Files listed with ? in front are not in SVN and possibly need to be added by you: +Files listed with ? in front are not in SVN and possibly need to be added by +you: svn add src/pluguns/grass/modules/foo.xml @@ -694,82 +763,90 @@ Commit your changes svn commit src/pluguns/grass/modules/foo.xml -Your editor (as defined in $EDITOR environment variable) will appear and you should make a - comment at the top of the file (above the area that says 'dont change this'. Put a -descriptive comment and rather do several small commits if the changes across a number of -files are unrelated. Conversely we prefer you to group related changes into a single commit. +Your editor (as defined in $EDITOR environment variable) will appear and you +should make a comment at the top of the file (above the area that says 'dont +change this'. Put a descriptive comment and rather do several small commits if +the changes across a number of files are unrelated. Conversely we prefer you to +group related changes into a single commit. -Save and close in your editor. The first time you do this, you should be prompted to -put in your username and password. Just use the same ones as your trac account. +Save and close in your editor. The first time you do this, you should be +prompted to put in your username and password. Just use the same ones as your +trac account. 3. Unit Testing =============== -As of November 2007 we require all new features going into trunk to be accompanied with -a unit test. Initially we have limited this requirement to qgis_core, and we will extend -this requirement to other parts of the code base once people are familiar with the -procedures for unit testing explained in the sections that follow. +As of November 2007 we require all new features going into trunk to be +accompanied with a unit test. Initially we have limited this requirement to +qgis_core, and we will extend this requirement to other parts of the code base +once people are familiar with the procedures for unit testing explained in the +sections that follow. - 3.1. The QGIS testing framework - an overview - ============================================== + 3.1. The QGIS testing framework - an overview + ============================================== -Unit testing is carried out using a combination of QTestLib (the Qt testing library) and -CTest (a framework for compiling and running tests as part of the CMake build process). -Lets take an overview of the process before I delve into the details: +Unit testing is carried out using a combination of QTestLib (the Qt testing +library) and CTest (a framework for compiling and running tests as part of the +CMake build process). Lets take an overview of the process before I delve into +the details: - * There is some code you want to test, e.g. a class or function. Extreme programming - advocates suggest that the code should not even be written yet when you start - building your tests, and then as you implement your code you can immediately validate - each new functional part you add with your test. In practive you will probably - need to write tests for pre-existing code in QGIS since we are starting with a testing - framework well after much application logic has already been implemented. +- There is some code you want to test, e.g. a class or function. Extreme + programming advocates suggest that the code should not even be written yet + when you start building your tests, and then as you implement your code you can + immediately validate each new functional part you add with your test. In + practive you will probably need to write tests for pre-existing code in QGIS + since we are starting with a testing framework well after much application + logic has already been implemented. - * You create a unit test. This happens under /tests/src/core - in the case of the core lib. The test is basically a client that creates an instance - of a class and calls some methods on that class. It will check the return from each - method to make sure it matches the expected value. If any one of the calls fails, - the unit will fail. +- You create a unit test. This happens under /tests/src/core + in the case of the core lib. The test is basically a client that creates an + instance of a class and calls some methods on that class. It will check the + return from each method to make sure it matches the expected value. If any + one of the calls fails, the unit will fail. - * You include QtTestLib macros in your test class. This macro is processed by - the Qt meta object compiler (moc) and expands your test class into a runnable application. +- You include QtTestLib macros in your test class. This macro is processed by + the Qt meta object compiler (moc) and expands your test class into a + runnable application. - * You add a section to the CMakeLists.txt in your tests directory that will +- You add a section to the CMakeLists.txt in your tests directory that will build your test. - * You ensure you have ENABLE_TESTING enabled in ccmake / cmakesetup. This +- You ensure you have ENABLE_TESTING enabled in ccmake / cmakesetup. This will ensure your tests actually get compiled when you type make. - * You optionally add test data to /tests/testdata if your - test is data driven (e.g. needs to load a shapefile). These test data should be - as small as possible and wherever possible you should use the existing datasets - already there. Your tests should never modify this data in situ, but rather - may a temporary copy somewhere if needed. +- You optionally add test data to /tests/testdata if your + test is data driven (e.g. needs to load a shapefile). These test data should + be as small as possible and wherever possible you should use the existing + datasets already there. Your tests should never modify this data in situ, + but rather may a temporary copy somewhere if needed. - * You compile your sources and install. Do this using normal make && (sudo) +- You compile your sources and install. Do this using normal make && (sudo) make install procedure. - * You run your tests. This is normally done simply by doing make test - after the make install step, though I will explain other aproaches that offer more - fine grained control over running tests. - -Right with that overview in mind, I will delve into a bit of detail. I've already -done much of the configuration for you in CMake and other places in the source tree -so all you need to do are the easy bits - writing unit tests! +- You run your tests. This is normally done simply by doing make test + after the make install step, though I will explain other aproaches that offer + more fine grained control over running tests. - 3.2. Creating a unit test - ========================= -Creating a unit test is easy - typically you will do this by just creating a +Right with that overview in mind, I will delve into a bit of detail. I've +already done much of the configuration for you in CMake and other places in the +source tree so all you need to do are the easy bits - writing unit tests! + + + 3.2. Creating a unit test + ========================= + +Creating a unit test is easy - typically you will do this by just creating a single .cpp file (not .h file is used) and implement all your test methods as -public methods that return void. I'll use a simple test class for QgsRasterLayer -throughout the section that follows to illustrate. By convention we will name our -test with the same name as the class they are testing but prefixed with 'Test'. -So our test implementation goes in a file called testqgsrasterlayer.cpp and -the class itself will be TestQgsRasterLayer. First we add our standard copyright -banner: +public methods that return void. I'll use a simple test class for +QgsRasterLayer throughout the section that follows to illustrate. By convention +we will name our test with the same name as the class they are testing but +prefixed with 'Test'. So our test implementation goes in a file called +testqgsrasterlayer.cpp and the class itself will be TestQgsRasterLayer. First +we add our standard copyright banner: /*************************************************************************** @@ -813,11 +890,11 @@ in whatever headers you may need: #include -Since we are combining both class declaration and implementation in a single -file the class declaration comes next. We start with our doxygen documentation. -Every test case should be properly documented. We use the doxygen ingroup -directive so that all the UnitTests appear as a module in the generated -Doxygen documentation. After that comes a short description of the unit test: +Since we are combining both class declaration and implementation in a single +file the class declaration comes next. We start with our doxygen documentation. +Every test case should be properly documented. We use the doxygen ingroup +directive so that all the UnitTests appear as a module in the generated Doxygen +documentation. After that comes a short description of the unit test: /** \ingroup UnitTests @@ -833,108 +910,102 @@ The class must inherit from QObject and include the Q_OBJECT macro. Q_OBJECT; -All our test methods are implemented as private slots. The QtTest framework -will sequentially call each private slot method in the test class. There are -four 'special' methods which if implemented will be called at the start of -the unit test (initTestCase), at the end of the unit test (cleanupTestCase). -Before each test method is called, the init() method will be called and -after each test method is called the cleanup() method is called. These -methods are handy in that they allow you to allocate and cleanup resources -prior to running each test, and the test unit as a whole. +All our test methods are implemented as private slots. The QtTest framework +will sequentially call each private slot method in the test class. There are +four 'special' methods which if implemented will be called at the start of the +unit test (initTestCase), at the end of the unit test +(cleanupTestCase). Before each test method is called, the init() +method will be called and after each test method is called the cleanup() +method is called. These methods are handy in that they allow you to allocate +and cleanup resources prior to running each test, and the test unit as a whole. private slots: - // will be called before the first testfunction is executed. - void initTestCase(); - // will be called after the last testfunction was executed. - void cleanupTestCase(){}; - // will be called before each testfunction is executed. - void init(){}; - // will be called after every testfunction. - void cleanup(); + // will be called before the first testfunction is executed. + void initTestCase(); + // will be called after the last testfunction was executed. + void cleanupTestCase(){}; + // will be called before each testfunction is executed. + void init(){}; + // will be called after every testfunction. + void cleanup(); -Then come your test methods, all of which should take no parameters and -should return void. The methods will be called in order of declaration. -I am implementing two methods here which illustrates to types of testing. In -the first case I want to generally test the various parts of the class are -working, I can use a functional testing approach. Once again, extreme -programmers would advocate writing these tests before implementing the -class. Then as you work your way through your class implementation you -iteratively run your unit tests. More and more test functions should complete -sucessfully as your class implementation work progresses, and when the whole -unit test passes, your new class is done and is now complete with a repeatable -way to validate it. +Then come your test methods, all of which should take no parameters and +should return void. The methods will be called in order of declaration. I +am implementing two methods here which illustrates to types of testing. In the +first case I want to generally test the various parts of the class are working, +I can use a functional testing approach. Once again, extreme programmers +would advocate writing these tests before implementing the class. Then as +you work your way through your class implementation you iteratively run your +unit tests. More and more test functions should complete sucessfully as your +class implementation work progresses, and when the whole unit test passes, your +new class is done and is now complete with a repeatable way to validate it. -Typically your unit tests would only cover the public API of your -class, and normally you do not need to write tests for accessors and mutators. -If it should happen that an acccessor or mutator is not working as expected -you would normally implement a regression test to check for this (see -lower down). +Typically your unit tests would only cover the public API of your class, +and normally you do not need to write tests for accessors and mutators. If it +should happen that an acccessor or mutator is not working as expected you would +normally implement a regression test to check for this (see lower down). - // - // Functional Testing - // - - /** Check if a raster is valid. */ - void isValid(); + // + // Functional Testing + // + + /** Check if a raster is valid. */ + void isValid(); - // more functional tests here ... + // more functional tests here ... -Next we implement our regression tests. Regression tests should be -implemented to replicate the conditions of a particular bug. For example -I recently received a report by email that the cell count by rasters was -off by 1, throwing off all the statistics for the raster bands. I opened -a bug (ticket #832) and then created a regression test that replicated -the bug using a small test dataset (a 10x10 raster). Then I ran the test -and ran it, verifying that it did indeed fail (the cell count was 99 -instead of 100). Then I went to fix the bug and reran the unit test and -the regression test passed. I committed the regression test along with -the bug fix. Now if anybody breakes this in the source code again in the -future, we can immediatly identify that the code has regressed. Better -yet before committing any changes in the future, running our tests will -ensure our changes dont have unexpected side effects - like breaking +Next we implement our regression tests. Regression tests should be +implemented to replicate the conditions of a particular bug. For example I +recently received a report by email that the cell count by rasters was off by +1, throwing off all the statistics for the raster bands. I opened a bug (ticket +#832) and then created a regression test that replicated the bug using a small +test dataset (a 10x10 raster). Then I ran the test and ran it, verifying that +it did indeed fail (the cell count was 99 instead of 100). Then I went to fix +the bug and reran the unit test and the regression test passed. I committed the +regression test along with the bug fix. Now if anybody breakes this in the +source code again in the future, we can immediatly identify that the code has +regressed. Better yet before committing any changes in the future, running our +tests will ensure our changes dont have unexpected side effects - like breaking existing functionality. -There is one more benifit to regression tests - they can save you time. -If you ever fixed a bug that involved making changes to the source, -and then running the application and performing a series of convoluted -steps to replicate the issue, it will be immediately apparent that -simply implementing your regression test before fixing the bug -will let you automate the testing for bug resolution in an efficient -manner. +There is one more benifit to regression tests - they can save you time. If you +ever fixed a bug that involved making changes to the source, and then running +the application and performing a series of convoluted steps to replicate the +issue, it will be immediately apparent that simply implementing your regression +test before fixing the bug will let you automate the testing for bug +resolution in an efficient manner. -To implement your regression test, you should follow the naming -convention of regression for your test functions. If no -trac ticket exists for the regression, you should create one first. -Using this approach allows the person running a failed regression -test easily go and find out more information. +To implement your regression test, you should follow the naming convention of +regression for your test functions. If no trac ticket exists for the +regression, you should create one first. Using this approach allows the person +running a failed regression test easily go and find out more information. - // - // Regression Testing - // - - /** This is our second test case...to check if a raster - reports its dimensions properly. It is a regression test - for ticket #832 which was fixed with change r7650. - */ - void regression832(); + // + // Regression Testing + // - // more regression tests go here ... + /** This is our second test case...to check if a raster + reports its dimensions properly. It is a regression test + for ticket #832 which was fixed with change r7650. + */ + void regression832(); + + // more regression tests go here ... -Finally in our test class declaration you can declare privately -any data members and helper methods your unit test may need. In our -case I will declare a QgsRasterLayer * which can be used by any -of our test methods. The raster layer will be created in the -initTestCase() function which is run before any other tests, and then -destroyed using cleanupTestCase() which is run after all tests. By -declaring helper methods (which may be called by various test -functions) privately, you can ensure that they wont be automatically -run by the QTest executeable that is created when we compile our test. +Finally in our test class declaration you can declare privately any data +members and helper methods your unit test may need. In our case I will declare +a QgsRasterLayer * which can be used by any of our test methods. The raster +layer will be created in the initTestCase() function which is run before any +other tests, and then destroyed using cleanupTestCase() which is run after all +tests. By declaring helper methods (which may be called by various test +functions) privately, you can ensure that they wont be automatically run by the +QTest executeable that is created when we compile our test. private: @@ -945,8 +1016,8 @@ run by the QTest executeable that is created when we compile our test. -That ends our class declaration. The implementation is simply -inlined in the same file lower down. First our init and cleanup functions: +That ends our class declaration. The implementation is simply inlined in the +same file lower down. First our init and cleanup functions: void TestQgsRasterLayer::initTestCase() @@ -997,11 +1068,10 @@ Qt also provides some other interesting mechanisms for data driven testing, so if you are interested to know more on the topic, consult the Qt documentation. -Next lets look at our functional test. The isValid() test simply -checks the raster layer was correctly loaded in the initTestCase. -QVERIFY is a Qt macro that you can use to evaluate a test condition. -There are a few other use macros Qt provide for use in your tests -including: +Next lets look at our functional test. The isValid() test simply checks the +raster layer was correctly loaded in the initTestCase. QVERIFY is a Qt macro +that you can use to evaluate a test condition. There are a few other use +macros Qt provide for use in your tests including: QCOMPARE ( actual, expected ) @@ -1018,8 +1088,8 @@ including: QWARN ( message ) -Some of these macros are useful only when using the Qt framework -for data driven testing (see the Qt docs for more detail). +Some of these macros are useful only when using the Qt framework for data +driven testing (see the Qt docs for more detail). void TestQgsRasterLayer::isValid() @@ -1028,13 +1098,13 @@ for data driven testing (see the Qt docs for more detail). } -Normally your functional tests would cover all the range of -functionality of your classes public API where feasible. With our -functional tests out the way, we can look at our regression test example. +Normally your functional tests would cover all the range of functionality of +your classes public API where feasible. With our functional tests out the way, +we can look at our regression test example. -Since the issue in bug #832 is a misreported cell count, writing -our test if simply a matter of using QVERIFY to check that the -cell count meets the expected value: +Since the issue in bug #832 is a misreported cell count, writing our test if +simply a matter of using QVERIFY to check that the cell count meets the +expected value: void TestQgsRasterLayer::regression832() @@ -1047,27 +1117,26 @@ cell count meets the expected value: } -With all the unit test functions implemented, there one final thing we -need to add to our test class: +With all the unit test functions implemented, there one final thing we need to +add to our test class: QTEST_MAIN(TestQgsRasterLayer) #include "moc_testqgsrasterlayer.cxx" -The purpose of these two lines is to signal to Qt's moc that his is a -QtTest (it will generate a main method that in turn calls each test funtion. -The last line is the include for the MOC generated sources. You should -replace 'testqgsrasterlayer' with the name of your class in lower case. +The purpose of these two lines is to signal to Qt's moc that his is a QtTest +(it will generate a main method that in turn calls each test funtion. The last +line is the include for the MOC generated sources. You should replace +'testqgsrasterlayer' with the name of your class in lower case. - 3.3. Adding your unit test to CMakeLists.txt - ============================================ + 3.3. Adding your unit test to CMakeLists.txt + ============================================ -Adding your unit test to the build system is simply a matter of editing -the CMakeLists.txt in the test directory, cloning one of the existing -test blocks, and then search and replacing your test class name into it. -For example: +Adding your unit test to the build system is simply a matter of editing the +CMakeLists.txt in the test directory, cloning one of the existing test blocks, +and then search and replacing your test class name into it. For example: # @@ -1084,23 +1153,23 @@ For example: ADD_TEST(qgis_rasterlayertest ${QGIS_BIN_DIR}/qgis_rasterlayertest) -I'll run through these lines briefly to explain what they do, but if -you are not interested, just clone the block, search and replace e.g. +I'll run through these lines briefly to explain what they do, but if you are +not interested, just clone the block, search and replace e.g. :'<,'>s/rasterlayer/mynewtest/g -Lets look a little more in detail at the individual lines. First we -define the list of sources for our test. Since we have only one source file -(following the methodology I described above where class declaration and -definition are in the same file) its a simple statement: +Lets look a little more in detail at the individual lines. First we define the +list of sources for our test. Since we have only one source file (following the +methodology I described above where class declaration and definition are in the +same file) its a simple statement: SET(qgis_rasterlayertest_SRCS testqgsrasterlayer.cpp) -Since our test class needs to be run through the Qt meta object compiler (moc) +Since our test class needs to be run through the Qt meta object compiler (moc) we need to provide a couple of lines to make that happen too: @@ -1109,73 +1178,70 @@ we need to provide a couple of lines to make that happen too: ADD_CUSTOM_TARGET(qgis_rasterlayertestmoc ALL DEPENDS ${qgis_rasterlayertest_MOC_SRCS}) -Next we tell cmake that it must make an executeable from the test class. -Remember in the previous section on the last line of the class implementation -I included the moc outputs directly into our test class, so that will -give it (among other things) a main method so the class can be -compiled as an executeable: +Next we tell cmake that it must make an executeable from the test class. +Remember in the previous section on the last line of the class implementation I +included the moc outputs directly into our test class, so that will give it +(among other things) a main method so the class can be compiled as an +executeable: ADD_EXECUTABLE(qgis_rasterlayertest ${qgis_rasterlayertest_SRCS}) ADD_DEPENDENCIES(qgis_rasterlayertest qgis_rasterlayertestmoc) -Next we need to specify any library dependencies. At the moment classes -have been implemented with a catch-all QT_LIBRARIES dependency, but I will -be working to replace that with the specific Qt libraries that each class -needs only. Of course you also need to link to the relevant qgis -libraries as required by your unit test. +Next we need to specify any library dependencies. At the moment classes have +been implemented with a catch-all QT_LIBRARIES dependency, but I will be +working to replace that with the specific Qt libraries that each class needs +only. Of course you also need to link to the relevant qgis libraries as +required by your unit test. TARGET_LINK_LIBRARIES(qgis_rasterlayertest ${QT_LIBRARIES} qgis_core) -Next I tell cmake to the same place as the qgis binaries itself. This -is something I plan to remove in the future so that the tests can -run directly from inside the source tree. +Next I tell cmake to the same place as the qgis binaries itself. This is +something I plan to remove in the future so that the tests can run directly +from inside the source tree. INSTALL(TARGETS qgis_rasterlayertest RUNTIME DESTINATION ${QGIS_BIN_DIR}) -Finally here is where the best magic happens - we register the class with -ctest. If you recall in the overview I gave in the beginning of this -section we are using both QtTest and CTest together. To recap, QtTest adds a -main method to your test unit and handles calling your test methods within -the class. It also provides some macros like QVERIFY that you can use as -to test for failure of the tests using conditions. The output from -a QtTest unit test is an executeable which you can run from the command line. -However when you have a suite of tests and you want to run each executeable -in turn, and better yet integrate running tests into the build process, -the CTest is what we use. The next line registers the unit test with -CMake / CTest. +Finally here is where the best magic happens - we register the class with +ctest. If you recall in the overview I gave in the beginning of this section we +are using both QtTest and CTest together. To recap, QtTest adds a main +method to your test unit and handles calling your test methods within the +class. It also provides some macros like QVERIFY that you can use as to test +for failure of the tests using conditions. The output from a QtTest unit test +is an executeable which you can run from the command line. However when you +have a suite of tests and you want to run each executeable in turn, and +better yet integrate running tests into the build process, the CTest is +what we use. The next line registers the unit test with CMake / CTest. ADD_TEST(qgis_rasterlayertest ${QGIS_BIN_DIR}/qgis_rasterlayertest) -The last thing I should add is that if your test requires optional -parts of the build process (e.g. Postgresql support, GSL libs, GRASS etc.), -you should take care to enclose you test block inside a IF () block -in the CMakeLists.txt file. +The last thing I should add is that if your test requires optional parts of the +build process (e.g. Postgresql support, GSL libs, GRASS etc.), you should take +care to enclose you test block inside a IF () block in the CMakeLists.txt file. - 3.4. Building your unit test - ============================ + 3.4. Building your unit test + ============================ -To build the unit test you need only to make sure that ENABLE_TESTS=true -in the cmake configuration. There are two ways to do this: +To build the unit test you need only to make sure that ENABLE_TESTS=true in the +cmake configuration. There are two ways to do this: 1. Run ccmake .. (cmakesetup .. under windows) and interactively set the ENABLE_TESTS flag to ON. 1. Add a command line flag to cmake e.g. cmake -DENABLE_TESTS=true .. -Other than that, just build QGIS as per normal and the tests should build -too. +Other than that, just build QGIS as per normal and the tests should build too. - 3.5. Run your tests - =================== + 3.5. Run your tests + =================== The simplest way to run the tests is as part of your normal build process: @@ -1183,9 +1249,9 @@ The simplest way to run the tests is as part of your normal build process: make && make install && make test -The make test command will invoke CTest which will run each test that -was registered using the ADD_TEST CMake directive described above. Typical -output from make test will look like this: +The make test command will invoke CTest which will run each test that was +registered using the ADD_TEST CMake directive described above. Typical output +from make test will look like this: Running tests... @@ -1203,9 +1269,9 @@ output from make test will look like this: make: *** [test] Error 8 -If a test fails, you can use the ctest command to examine more -closely why it failed. User the -R option to specify a regex for -which tests you want to run and -V to get verbose output: +If a test fails, you can use the ctest command to examine more closely why it +failed. User the -R option to specify a regex for which tests you want to run +and -V to get verbose output: [build] ctest -R appl -V @@ -1247,56 +1313,59 @@ which tests you want to run and -V to get verbose output: -Well that concludes this section on writing unit tests in QGIS. We hope you -will get into the habit of writing test to test new functionality and to -check for regressions. Some aspects of the test system (in particular the -CMakeLists.txt parts) are still being worked on so that the testing framework -works in a truly platform way. I will update this document as things progress. +Well that concludes this section on writing unit tests in QGIS. We hope you +will get into the habit of writing test to test new functionality and to check +for regressions. Some aspects of the test system (in particular the +CMakeLists.txt parts) are still being worked on so that the testing framework +works in a truly platform way. I will update this document as things +progress. 4. HIG (Human Interface Guidelines) =================================== -In order for all graphical user interface elements to appear consistant and -to all the user to instinctively use dialogs, it is important that the following +In order for all graphical user interface elements to appear consistant and to +all the user to instinctively use dialogs, it is important that the following guidelines are followed in layout and design of GUIs. 1. Group related elements using group boxes: - Try to identify elements that can be grouped together and then use - group boxes with a label to identify the topic of that group. - Avoid using group boxes with only a single widget / item inside. + Try to identify elements that can be grouped together and then use group + boxes with a label to identify the topic of that group. Avoid using group + boxes with only a single widget / item inside. 2. Capitalise first letter only in labels: - Labels (and group box labels) should be written as a phrase with leading capital letter, - and all remaing words written with lower case first letters + Labels (and group box labels) should be written as a phrase with leading + capital letter, and all remaing words written with lower case first letters 3. Do not end labels for widgets or group boxes with a colon: Adding a colon causes visual noise and does not impart additional meaning, - so dont use them. An exception to this rule is when you have two labels - next to each other e.g.: Label1 Plugin (Path:) Label2 [/path/to/plugins] + so dont use them. An exception to this rule is when you have two labels next + to each other e.g.: Label1 Plugin (Path:) Label2 [/path/to/plugins] 4. Keep harmful actions away from harmless ones: - If you have actions for 'delete', 'remove' etc, try to impose adequate - space between the harmful action and innocuous actions so that the users - is less likely to inadvertantly click on the harmful action. + If you have actions for 'delete', 'remove' etc, try to impose adequate space + between the harmful action and innocuous actions so that the users is less + likely to inadvertantly click on the harmful action. 5. Always use a QButtonBox for 'OK', 'Cancel' etc buttons: - Using a button box will ensure that the order of 'OK' and 'Cancel' etc, - buttons is consistent with the operating system / locale / desktop + Using a button box will ensure that the order of 'OK' and 'Cancel' etc, + buttons is consistent with the operating system / locale / desktop environment that the user is using. 5. Authors ========== - * Tim Sutton (author and editor) - * Gary Sherman - * Marco Hugentobler +- Tim Sutton (author and editor) +- Gary Sherman +- Marco Hugentobler + Original pages from wiki to deprecate: - * http://wiki.qgis.org/qgiswiki/CodingGuidelines (./) - * http://wiki.qgis.org/qgiswiki/CodingStandards (./) - * http://wiki.qgis.org/qgiswiki/UsingSubversion (./) - * http://wiki.qgis.org/qgiswiki/DebuggingPlugins - * http://wiki.qgis.org/qgiswiki/DevelopmentInBranches (./) - * http://wiki.qgis.org/qgiswiki/SubmittingPatchesAndSvnAccess (./) +- http://wiki.qgis.org/qgiswiki/CodingGuidelines (./) +- http://wiki.qgis.org/qgiswiki/CodingStandards (./) +- http://wiki.qgis.org/qgiswiki/UsingSubversion (./) +- http://wiki.qgis.org/qgiswiki/DebuggingPlugins +- http://wiki.qgis.org/qgiswiki/DevelopmentInBranches (./) +- http://wiki.qgis.org/qgiswiki/SubmittingPatchesAndSvnAccess (./) + diff --git a/INSTALL b/INSTALL index 929dac0d494..954294c7659 100644 --- a/INSTALL +++ b/INSTALL @@ -38,11 +38,7 @@ Building QGIS from source - step by step 4.5. Install subversion for OSX 4.6. Check out QGIS from SVN 4.7. Configure the build - 4.7.1. Configure the Cmake build - 4.7.2. Configure the Xcode Build 4.8. Building - 4.8.1 Building with Cmake - 4.8.2. Building with Xcode 5. Building on GNU/Linux 5.1. Building QGIS with Qt4.x 5.2. Prepare apt @@ -143,6 +139,11 @@ and getting involved in the project further. /!\ *Note to document writers:* Please use this document as the central place for describing build procedures. Please do not remove this notice. +/!\ *Note to document writers:* This documented is generated from +doc/INSTALL.t2t - if you need to edit this document, be sure to edit that +file rather than the generated INSTALL document found in the root of the +source directory. + /!\ *Note:* This is a 'cut and paste' tutorial - in most cases you can simply copy the commands listed in codeblocks that look like this: @@ -163,8 +164,8 @@ For complete information, see the wiki at: http://wiki.qgis.org/qgiswiki/Building_with_CMake - 2.1. An overview of the dependencies required for building - ========================================================== + 2.1. An overview of the dependencies required for building + ========================================================== '''Required build deps:''' * CMake >= 2.4.3 @@ -199,8 +200,8 @@ http://www.webalice.it/marco.pasetti/qgis+grass/BuildFromSource.html Read on to use the simplified approach with pre-built libraries... - 3.1. MSYS: - ========== + 3.1. MSYS: + ========== MSYS provides a unix style build environment under windows. We have created a zip archive that contains just about all dependencies. @@ -216,8 +217,8 @@ our pre-made one, detailed instructions are provided elsewhere in this document. - 3.2. Qt4.3 - ========== + 3.2. Qt4.3 + ========== Download qt4.3 opensource precompiled edition exe and install (including the download and install of mingw) from here: @@ -252,8 +253,8 @@ following command: - 3.3. Flex and Bison - =================== + 3.3. Flex and Bison + =================== *** Note I think this section can be removed as it should be installed int the msys image already. TS @@ -263,24 +264,24 @@ http://sourceforge.net/project/showfiles.php?group_id=23617&package_id=16424 (the zip bin) and extract it into c:\msys\mingw\bin - 3.4. Python stuff: (optional) - ============================= + 3.4. Python stuff: (optional) + ============================= Follow this section in case you would like to use Python bindings for QGIS. To be able to compile bindings, you need to compile SIP and PyQt4 from sources as their installer doesn't include some development files which are necessary. - 3.4.1. Download and install Python - use Windows installer - ========================================================== + 3.4.1. Download and install Python - use Windows installer + ========================================================== (It doesn't matter to what folder you'll install it) http://python.org/download/ - 3.4.2. Download SIP and PyQt4 sources - ===================================== + 3.4.2. Download SIP and PyQt4 sources + ===================================== http://www.riverbankcomputing.com/software/sip/download http://www.riverbankcomputing.com/software/pyqt/download @@ -289,8 +290,8 @@ Extract each of the above zip files in a temporary directory. Make sure to get versions that match your current Qt installed version. - 3.4.3. Compile SIP - ================== + 3.4.3. Compile SIP + ================== c:\Qt\4.3.0\bin\qtvars.bat @@ -300,8 +301,8 @@ to get versions that match your current Qt installed version. - 3.4.4. Compile PyQt - =================== + 3.4.4. Compile PyQt + =================== c:\Qt\4.3.0\bin\qtvars.bat @@ -311,15 +312,15 @@ to get versions that match your current Qt installed version. - 3.4.5. Final python notes - ========================= + 3.4.5. Final python notes + ========================= /!\ You can delete the directories with unpacked SIP and PyQt4 sources after a successfull install, they're not needed anymore. - 3.5. Subversion: - ================ + 3.5. Subversion: + ================ In order to check out QGIS sources from the repository, you need Subversion client. This installer should work fine: @@ -327,16 +328,16 @@ client. This installer should work fine: http://subversion.tigris.org/files/documents/15/36797/svn-1.4.3-setup.exe - 3.6. CMake: - =========== + 3.6. CMake: + =========== CMake is build system used by Quantum GIS. Download it from here: http://www.cmake.org/files/v2.4/cmake-2.4.6-win32-x86.exe - 3.7. QGIS: - ========== + 3.7. QGIS: + ========== Start a cmd.exe window ( Start -> Run -> cmd.exe ) Create development directory and move into it @@ -358,8 +359,8 @@ For svn 0.8 branch - 3.8. Compiling: - =============== + 3.8. Compiling: + =============== As a background read the generic building with CMake notes at the end of this document. @@ -382,8 +383,8 @@ Create build directory and set it as current directory: - 3.9. Configuration - ================== + 3.9. Configuration + ================== cmakesetup .. @@ -407,16 +408,16 @@ install prefix to its default c:\program files\ When configuration is done, click 'OK' to exit the setup utility. - 3.10. Compilation and installation - ================================== + 3.10. Compilation and installation + ================================== make make install - 3.11. Run qgis.exe from the directory where it's installed (CMAKE_INSTALL_PREFIX) - ================================================================================= + 3.11. Run qgis.exe from the directory where it's installed (CMAKE_INSTALL_PREFIX) + ================================================================================= Make sure to copy all .dll:s needed to the same directory as the qgis.exe binary is installed to, if not already done so, otherwise QGIS will complain @@ -436,8 +437,8 @@ c:\msys\local\bin and c:\msys\local\lib directories, so the DLLs will be used from that place. - 3.12. Create the installation package: (optional) - ================================================= + 3.12. Create the installation package: (optional) + ================================================= Downlad and install NSIS from (http://nsis.sourceforge.net/Main_Page) @@ -455,8 +456,8 @@ from source and rather use frameworks wherever possible. Included are a few notes for building on Mac OS X 10.5 (Leopard). - 4.1. Install XCODE - ================== + 4.1. Install XCODE + ================== I recommend to get the latest xcode dmg from the Apple XDC Web site. Install XCODE after the ~941mb download is complete. @@ -471,25 +472,21 @@ the XCODE SDK (in particular if you are using XCODE 2.5 on tiger): - 4.2. Install Qt4 from .dmg - ========================== + 4.2. Install Qt4 from .dmg + ========================== You need a minimum of Qt4.3.0. I suggest getting the latest (at time of writing). - ftp://ftp.trolltech.com/qt/source/ + ftp://ftp.trolltech.com/qt/source/qt-mac-opensource-4.3.2.dmg -Mac versions are named as: +If you want debug libs, Qt also provide a dmg with these: - qt-mac-opensource-x.y.z.dmg + ftp://ftp.trolltech.com/qt/source/qt-mac-opensource-4.3.2-debug-libs.dmg -x, y, z being the major, minor and revision version. - -If you want debug libs, Qt also provide a dmg with these. - I am going to proceed using only release libs at this stage as the download for the debug dmg is substantially bigger. If you plan to do any debugging though you probably want to get the debug libs dmg. Once downloaded open the dmg and @@ -500,7 +497,7 @@ After installing you need to make two small changes: First edit /Library/Frameworks/QtCore.framework/Headers/qconfig.h and change -/!\ Note: this isn't needed since version 4.2.3. +/!\ Note this doesnt seem to be needed since version 4.2.3 QT_EDITION_Unknown to QT_EDITION_OPENSOURCE @@ -512,11 +509,9 @@ Second change the default mkspec symlink so that it points to macx-g++: sudo ln -sf macx-g++ default -/!\ Note: this doesn't seem to be needed since version 4.4. - - 4.3. Install development frameworks for QGIS dependencies - ========================================================= + 4.3. Install development frameworks for QGIS dependencies + ========================================================= Download William Kyngesburye's excellent all in one framework that includes proj, gdal, sqlite3 etc @@ -527,43 +522,40 @@ proj, gdal, sqlite3 etc Once downloaded, open and install the frameworks. -William provides an additional installer package for Postgresql/PostGIS. It's +William provides an additional installer package for Postgresql/PostGIS. Its available here: http://www.kyngchaos.com/wiki/software:postgres -Also available is a GRASS application: - - - http://www.kyngchaos.com/wiki/software:grass - - There are some additional dependencies that at the time of writing are not -provided as frameworks or installers so we will need to build these from source. +provided as frameworks so we will need to build these from source. - 4.3.1. Additional Dependencies : GSL - ==================================== + 4.3.1. Additional Dependencies : GSL + ==================================== -Retrieve the current version of the Gnu Scientific Library from +Retrieve the Gnu Scientific Library from - ftp://ftp.gnu.org/gnu/gsl/ + curl -O ftp://ftp.gnu.org/gnu/gsl/gsl-1.8.tar.gz -Then extract it and build it to a prefix of /usr/local. Double-click the source tarball to unpack it, then cd to the source folder and: +Then extract it and build it to a prefix of /usr/local: - ./configure + tar xvfz gsl-1.8.tar.gz + cd gsl-1.8 + ./configure --prefix=/usr/local make sudo make install + cd .. - 4.3.2. Additional Dependencies : Expat - ====================================== + 4.3.2. Additional Dependencies : Expat + ====================================== Get the expat sources: @@ -571,17 +563,18 @@ Get the expat sources: http://sourceforge.net/project/showfiles.php?group_id=10127 -Double-click the source tarball to unpack, then cd to the source folder and: - - ./configure + tar xvfz expat-2.0.0.tar.gz + cd expat-2.0.0 + ./configure --prefix=/usr/local make sudo make install + cd .. - 4.3.3. Additional Dependencies : SIP - ==================================== + 4.3.3. Additional Dependencies : SIP + ==================================== Make sure you have the latest Python fom @@ -597,12 +590,15 @@ Retrieve the python bindings toolkit SIP from http://www.riverbankcomputing.com/software/sip/download -Double-click the source tarball to unpack it, then cd to the source folder and (this installs by default into the Python framework): +Then extract and build it (this installs by default into the Python framework): + tar xvfz sip-.tar.gz + cd sip- python configure.py make sudo make install + cd .. Leopard notes @@ -614,8 +610,8 @@ If building on Leopard, using Leopard's bundled Python, SIP wants to install in - 4.3.4. Additional Dependencies : PyQt - ===================================== + 4.3.4. Additional Dependencies : PyQt + ===================================== If you encounter problems compiling PyQt using the instructions below you can also try adding python from your frameworks dir @@ -631,14 +627,17 @@ Retrieve the python bindings toolkit for Qt from http://www.riverbankcomputing.com/software/pyqt/download -Double-click the source tarball to unpack it, then cd to the source folder and (this installs by default into the Python framework): +Then extract and build it (this installs by default into the Python framework): + tar xvfz PyQt-mac + cd PyQt-mac export QTDIR=/Developer/Applications/Qt python configure.py yes make sudo make install + cd .. Leopard notes @@ -649,50 +648,53 @@ If building on Leopard, using Leopard's bundled Python, PyQt wants to install in python configure.py -d /Library/Python/2.5/site-packages -b /usr/local/bin -If there is a problem with undefined symbols in QtOpenGL on Leopard, edit QtOpenGL/makefile and add -undefined dynamic_lookup to LFLAGS. Then make again. +There may be a problem with undefined symbols in QtOpenGL on Leopard. Edit QtOpenGL/makefile and add -undefined dynamic_lookup to LFLAGS. - 4.3.5. Additional Dependencies : Bison - ====================================== + 4.3.5. Additional Dependencies : Bison + ====================================== Leopard note: Leopard includes Bison 2.3, so this step can be skipped on Leopard. The version of bison available by default on Mac OSX is too old so you need to -get a more recent one on your system. Download at least version 2.3 from: +get a more recent one on your system. Download if from: - ftp://ftp.gnu.org/gnu/bison/ + curl -O http://ftp.gnu.org/gnu/bison/bison-2.3.tar.gz -Now build and install it to a prefix of /usr/local. Double-click the source tarball, then cd to the source folder and: +Now build and install it to a prefix of /usr/local : + tar xvfz bison-2.3.tar.gz + cd bison-2.3 ./configure --prefix=/usr/local make sudo make install + cd .. - 4.4. Install CMAKE for OSX - ========================== + 4.4. Install CMAKE for OSX + ========================== Get the latest release from here: - http://www.cmake.org/cmake/resources/software.html + http://www.cmake.org/HTML/Download.html -Binary installers are available for OS X, but they are not recommended (2.4 versions install in /usr instead of /usr/local, and 2.6 versions are a strange application). Download the source. Double-click the source tarball, then cd to the source folder and: +At the time of writing the file I grabbed was: - ./bootstrap --docdir=/share/doc/CMake --mandir=/share/man - make - sudo make install + curl -O http://www.cmake.org/files/v2.4/cmake-2.4.6-Darwin-universal.dmg +Once downloaded open the dmg and run the installer - 4.5. Install subversion for OSX - =============================== + + 4.5. Install subversion for OSX + =============================== Leopard note: Leopard includes SVN, so this step can be skipped on Leopard. @@ -736,8 +738,8 @@ old) that is installed by MacOSX Now close and reopen your shell to get the updated vars. - 4.6. Check out QGIS from SVN - ============================ + 4.6. Check out QGIS from SVN + ============================ Now we are going to check out the sources for QGIS. First we will create a directory for working in: @@ -783,18 +785,8 @@ this: I suggest you press 'p' to accept the key permanently. - 4.7. Configure the build - ======================== - -There are 2 different methods to build QGIS. The traditional Cmake method, -and the new Xcode project (starting with QGIS 1.1). The Xcode project has -additional bundling steps, though some optional QGIS features are required due -to limited conditional compilation. The Cmake build handles optional features, -and some bundling steps are available with scripts in the mac directory. - - - 4.7.1. Configure the Cmake build - ================================ + 4.7. Configure the build + ======================== CMake supports out of source build so we will create a 'build' dir for the build process. By convention I build my software into a dir called 'apps' in @@ -824,9 +816,9 @@ version as required): cmake -D CMAKE_INSTALL_PREFIX=${HOME}/apps/ \ - -D GRASS_INCLUDE_DIR=/Applications/GRASS-6.4.app/Contents/MacOS/ + -D GRASS_INCLUDE_DIR=/Applications/GRASS-6.3.app/Contents/MacOS/ include \ - -D GRASS_PREFIX=/Applications/GRASS-6.4.app/Contents/MacOS \ + -D GRASS_PREFIX=/Applications/GRASS-6.3.app/Contents/MacOS \ -D CMAKE_BUILD_TYPE=Release \ .. @@ -837,34 +829,15 @@ path and version as required): cmake -D CMAKE_INSTALL_PREFIX=${HOME}/apps/ \ - -D GRASS_INCLUDE_DIR=/user/local/grass-6.4.0/include \ - -D GRASS_PREFIX=/user/local/grass-6.4.0 \ + -D GRASS_INCLUDE_DIR=/user/local/grass-6.3.0/include \ + -D GRASS_PREFIX=/user/local/grass-6.3.0 \ -D CMAKE_BUILD_TYPE=Release \ .. - 4.7.2. Configure the Xcode Build - ======================================= -In the mac/xcode folder in the source, duplicate the 'qgis_user-template.xcconfig' -file and name it 'qgis_user.xcconfig'. A default build will use the KyngChaos -frameworks, Postgres, GRASS 6.4, the python.org Python 2.5 and extra dependencies -as described above, and compile for the build OSX version, so no extra configuration -is necessary. If building on Leopard, you may want to use the system Python, which -requires editing qgis_user.xcconfig. - -See the mac/xcode/readme.rtf for details, if you need to customize the build. - -The default build will also bundle the Qt frameworks, Postgres library, and -other dependency libraries to create a self-contained package. The KyngChaos -frameworks and GRASS application are not bundled. - - - 4.8. Building - ============= - - 4.8.1 Building with Cmake - ========================= + 4.8. Building + ============= Now we can start the build process: @@ -878,22 +851,13 @@ If all built without errors you can then install it: make install - 4.8.2. Building with Xcode - ========================== - -Open the xcode project file in Xcode. Select 'Release' build configuration -and the 'Full Qgis' target, then build. - -The Qgis application will be found in the 'build/Release' folder in the xcode folder. -Copy this to whereever you like. - 5. Building on GNU/Linux ======================== - 5.1. Building QGIS with Qt4.x - ============================= + 5.1. Building QGIS with Qt4.x + ============================= Requires: Ubuntu Hardy / Debian derived distro @@ -912,8 +876,8 @@ in use for a while, you may need to just skip those steps which are irrelevant to you. - 5.2. Prepare apt - ================ + 5.2. Prepare apt + ================ The packages qgis depends on to build are available in the "universe" component of Ubuntu. This is not activated by default, so you need to activate it: @@ -931,8 +895,8 @@ Now update your local sources database: - 5.3. Install Qt4 - ================ + 5.3. Install Qt4 + ================ sudo apt-get install libqt4-core libqt4-debug \ @@ -977,8 +941,8 @@ Use the simple command line dialog that appears after running each of the above commands to select the Qt4 version of the relevant applications. - 5.4. Install additional software dependencies required by QGIS - ============================================================== + 5.4. Install additional software dependencies required by QGIS + ============================================================== sudo apt-get install gdal-bin libgdal1-dev libgeos-dev proj \ @@ -1001,8 +965,8 @@ If you do not have cmake installed already: - 5.5. GRASS Specific Steps - ========================= + 5.5. GRASS Specific Steps + ========================= /!\ *Note:* If you don't need to build with GRASS support, you can skip this section. @@ -1016,8 +980,8 @@ Now you can install grass from dapper: /!\ You may need to explicitly state your grass version e.g. libgdal1-1.3.2-grass - 5.6. Setup ccache (Optional) - ============================ + 5.6. Setup ccache (Optional) + ============================ You should also setup ccache to speed up compile times: @@ -1028,8 +992,8 @@ You should also setup ccache to speed up compile times: - 5.7. Prepare your development environment - ========================================= + 5.7. Prepare your development environment + ========================================= As a convention I do all my development work in $HOME/dev/, so in this case we will create a work environment for C++ development work like @@ -1043,8 +1007,8 @@ this: This directory path will be assumed for all instructions that follow. - 5.8. Check out the QGIS Source Code - =================================== + 5.8. Check out the QGIS Source Code + =================================== There are two ways the source can be checked out. Use the anonymous method if you do not have edit privaleges for the QGIS source repository, or use @@ -1082,8 +1046,8 @@ qgis.org certificate. Press 'p' to accept it permanently: - 5.9. Starting the compile - ========================= + 5.9. Starting the compile + ========================= /!\ *Note:* The next section describes howto build debian packages @@ -1126,8 +1090,8 @@ Now on with the build: It may take a little while to build depending on your platform. - 5.10. Building Debian packages - ============================== + 5.10. Building Debian packages + ============================== Instead of creating a personal installation as in the previous step you can also create debian package. This is done from the qgis root directory, where @@ -1157,16 +1121,16 @@ Install them using dpkg. E.g.: sudo dpkg -i \ - ../qgis_1.0preview16_amd64.deb \ - ../libqgis-gui1_1.0preview16_amd64.deb \ - ../libqgis-core1_1.0preview16_amd64.deb \ - ../qgis-plugin-grass_1.0preview16_amd64.deb \ - ../python-qgis_1.0preview16_amd64.deb + ../qgis_1.0preview16_amd64.deb \ + ../libqgis-gui1_1.0preview16_amd64.deb \ + ../libqgis-core1_1.0preview16_amd64.deb \ + ../qgis-plugin-grass_1.0preview16_amd64.deb \ + ../python-qgis_1.0preview16_amd64.deb - 5.11. Running QGIS - ================== + 5.11. Running QGIS + ================== Now you can try to run QGIS: @@ -1182,59 +1146,59 @@ on your screen. ============================================================== - 6.1. Initial setup - ================== + 6.1. Initial setup + ================== - 6.1.1. MSYS - =========== + 6.1.1. MSYS + =========== This is the environment that supplies many utilities from UNIX world in Windows and is needed by many dependencies to be able to compile. Download from here: - http://puzzle.dl.sourceforge.net/sourceforge/mingw/MSYS-1.0.11-2004.04.30-1.exe + http://puzzle.dl.sourceforge.net/sourceforge/mingw/MSYS-1.0.11-2004.04.30-1.exe Install to c:\msys All stuff we're going to compile is going to get to this directory (resp. its subdirs). - 6.1.2. MinGW - ============ + 6.1.2. MinGW + ============ Download from here: - http://puzzle.dl.sourceforge.net/sourceforge/mingw/MinGW-5.1.3.exe + http://puzzle.dl.sourceforge.net/sourceforge/mingw/MinGW-5.1.3.exe Install to c:\msys\mingw It suffices to download and install only g++ and mingw-make components. - 6.1.3. Flex and Bison - ===================== + 6.1.3. Flex and Bison + ===================== Flex and Bison are tools for generation of parsers, they're needed for GRASS and also QGIS compilation. Download the following packages: - http://gnuwin32.sourceforge.net/downlinks/flex-bin-zip.php + http://gnuwin32.sourceforge.net/downlinks/flex-bin-zip.php - http://gnuwin32.sourceforge.net/downlinks/bison-bin-zip.php + http://gnuwin32.sourceforge.net/downlinks/bison-bin-zip.php - http://gnuwin32.sourceforge.net/downlinks/bison-dep-zip.php + http://gnuwin32.sourceforge.net/downlinks/bison-dep-zip.php Unpack them all to c:\msys\local - 6.2. Installing dependencies - ============================ + 6.2. Installing dependencies + ============================ - 6.2.1. Getting ready - ==================== + 6.2.1. Getting ready + ==================== Paul Kelly did a great job and prepared a package of precompiled libraries for GRASS. The package currently includes: @@ -1250,17 +1214,17 @@ The package currently includes: It's available for download here: - http://www.stjohnspoint.co.uk/grass/wingrass-extralibs.tar.gz + http://www.stjohnspoint.co.uk/grass/wingrass-extralibs.tar.gz Moreover he also left the notes how to compile it (for those interested): - http://www.stjohnspoint.co.uk/grass/README.extralibs + http://www.stjohnspoint.co.uk/grass/README.extralibs Unpack the whole package to c:\msys\local - 6.2.2. GDAL level one - ===================== + 6.2.2. GDAL level one + ===================== Since Quantum GIS needs GDAL with GRASS support, we need to compile GDAL from source - Paul Kelly's package doesn't include GRASS support in GDAL. @@ -1272,7 +1236,7 @@ The idea is following: So, start with downloading GDAL sources: - http://download.osgeo.org/gdal/gdal141.zip + http://download.osgeo.org/gdal/gdal141.zip Unpack it to some directory, preferably c:\msys\local\src. @@ -1324,12 +1288,12 @@ Libtool on windows assumes a line length limit of 8192 for some reason and tries Make and make install should be hassle free after this. - 6.2.3. GRASS - ============ + 6.2.3. GRASS + ============ Grab sources from CVS or use a weekly snapshot, see: - http://grass.itc.it/devel/cvs.php + http://grass.itc.it/devel/cvs.php In MSYS console go to the directory where you've unpacked or checked out sources (e.g. c:\msys\local\src\grass-6.3.cvs) @@ -1351,14 +1315,14 @@ By the way, these pages might be useful: - http://geni.ath.cx/grass.html - 6.2.4. GDAL level two - ===================== + 6.2.4. GDAL level two + ===================== At this stage, we'll use GDAL sources we've used before, only the compilation will be a bit different. But first in order to be able to compile GDAL sources with current GRASS CVS, you need to patch them, here's what you need to change: - http://trac.osgeo.org/gdal/attachment/ticket/1587/plugin_patch_grass63.diff + http://trac.osgeo.org/gdal/attachment/ticket/1587/plugin_patch_grass63.diff (you can patch it by hand or use patch.exe in c:\msys\bin) Now in MSYS console go to the GDAL sources directory and run the same commands as in level one, only with these differences: @@ -1375,12 +1339,12 @@ Then again, edit gdal-config and change line with CONFIG_LIBS Now, GDAL should be able to work also with GRASS raster layers. - 6.2.5. GEOS - =========== + 6.2.5. GEOS + =========== Download the sources: - http://geos.refractions.net/geos-2.2.3.tar.bz2 + http://geos.refractions.net/geos-2.2.3.tar.bz2 Unpack to e.g. c:\msys\local\src @@ -1405,30 +1369,30 @@ Now, in MSYS console, go to the source directory and run: - 6.2.6. SQLITE - ============= + 6.2.6. SQLITE + ============= You can use precompiled DLL, no need to compile from source: Download this archive: - http://www.sqlite.org/sqlitedll-3_3_17.zip + http://www.sqlite.org/sqlitedll-3_3_17.zip and copy sqlite3.dll from it to c:\msys\local\lib Then download this archive: - http://www.sqlite.org/sqlite-source-3_3_17.zip + http://www.sqlite.org/sqlite-source-3_3_17.zip and copy sqlite3.h to c:\msys\local\include - 6.2.7. GSL - ========== + 6.2.7. GSL + ========== Download sources: - ftp://ftp.gnu.org/gnu/gsl/gsl-1.9.tar.gz + ftp://ftp.gnu.org/gnu/gsl/gsl-1.9.tar.gz Unpack to c:\msys\local\src @@ -1441,12 +1405,12 @@ Run from MSYS console in the source directory: - 6.2.8. EXPAT - ============ + 6.2.8. EXPAT + ============ Download sources: - http://dfn.dl.sourceforge.net/sourceforge/expat/expat-2.0.0.tar.gz + http://dfn.dl.sourceforge.net/sourceforge/expat/expat-2.0.0.tar.gz Unpack to c:\msys\local\src @@ -1459,18 +1423,18 @@ Run from MSYS console in the source directory: - 6.2.9. POSTGRES - =============== + 6.2.9. POSTGRES + =============== We're going to use precompiled binaries. Use the link below for download: - http://wwwmaster.postgresql.org/download/mirrors-ftp?file=%2Fbinary%2Fv8.2.4%2Fwin32%2Fpostgresql-8.2.4-1-binaries-no-installer.zip + http://wwwmaster.postgresql.org/download/mirrors-ftp?file=%2Fbinary%2Fv8.2.4%2Fwin32%2Fpostgresql-8.2.4-1-binaries-no-installer.zip copy contents of pgsql directory from the archive to c:\msys\local - 6.3. Cleanup - ============ + 6.3. Cleanup + ============ We're done with preparation of MSYS environment. Now you can delete all stuff in c:\msys\local\src - it takes quite a lot of space and it's not necessary at all. @@ -1486,56 +1450,56 @@ and we focus just on getting Visual Studio Express set up and building QGIS. Note that this does not currently include GRASS or Python plugins. - 7.1. Setup Visual Studio - ======================== + 7.1. Setup Visual Studio + ======================== This section describes the setup required to allow Visual Studio to be used to build QGIS. - 7.1.1. Express Edition - ====================== + 7.1.1. Express Edition + ====================== The free Express Edition lacks the platform SDK which contains headers and so on that are needed when building QGIS. The platform SDK can be installed as described here: - http://msdn.microsoft.com/vstudio/express/visualc/usingpsdk/ + http://msdn.microsoft.com/vstudio/express/visualc/usingpsdk/ Once this is done, you will need to edit the \Common7\Tools\vsvars file as follows: - Add %PlatformSDKDir%\Include\atl and %PlatformSDKDir%\Include\mfc to the @set INCLUDE entry. + Add %PlatformSDKDir%\Include\atl and %PlatformSDKDir%\Include\mfc to the @set INCLUDE entry. This will add more headers to the system INCLUDE path. Note that this will only work when you use the Visual Studio command prompt when building. Most of the dependencies will be built with this. You will also need to perform the edits described here to remove the need for a library that Visual Studio Express lacks: - http://www.codeproject.com/wtl/WTLExpress.asp + http://www.codeproject.com/wtl/WTLExpress.asp - 7.1.2. All Editions - =================== + 7.1.2. All Editions + =================== You will need stdint.h and unistd.h. unistd.h comes with GnuWin32 version of flex & bison binaries (see later). stdint.h can be found here: - http://www.azillionmonkeys.com/qed/pstdint.h. + http://www.azillionmonkeys.com/qed/pstdint.h. Copy both of these to \VC\include. - 7.2. Download/Install Dependencies - ================================== + 7.2. Download/Install Dependencies + ================================== This section describes the downloading and installation of the various QGIS dependencies. - 7.2.1. Flex and Bison - ===================== + 7.2.1. Flex and Bison + ===================== Flex and Bison are tools for generation of parsers, they're needed for GRASS and also QGIS compilation. Download the following packages and run the installers: - http://gnuwin32.sourceforge.net/downlinks/flex.php + http://gnuwin32.sourceforge.net/downlinks/flex.php - http://gnuwin32.sourceforge.net/downlinks/bison.php + http://gnuwin32.sourceforge.net/downlinks/bison.php - 7.2.2. To include PostgreSQL support in Qt - =========================================== + 7.2.2. To include PostgreSQL support in Qt + =========================================== If you want to build Qt with PostgreSQL support you need to download PostgreSQL, install it and create a library you can later link with Qt. @@ -1553,13 +1517,13 @@ PostgreSQL lib directory: /Dump of file / { - s/Dump of file \([^ ]*\)$/LIBRARY \1/p - a\ + s/Dump of file \([^ ]*\)$/LIBRARY \1/p + a\ EXPORTS } - /[ ]*ordinal hint/,/^[ ]*Summary/ { - /^[ ]\+[0-9]\+/ { - s/^[ ]\+[0-9]\+[ ]\+[0-9A-Fa-f]\+[ ]\+[0-9A-Fa-f]\+[ ]\+\([^ =]\+\).*$/ \1/p + /[ ]*ordinal hint/,/^[ ]*Summary/ { + /^[ ]\+[0-9]\+/ { + s/^[ ]\+[0-9]\+[ ]\+[0-9A-Fa-f]\+[ ]\+[0-9A-Fa-f]\+[ ]\+\([^ =]\+\).*$/ \1/p } } @@ -1579,20 +1543,20 @@ That's almost it. You only need to the include and lib path to INCLUDE and LIB in vcvars.bat respectively. - 7.2.3. Qt - ========= + 7.2.3. Qt + ========= Build Qt following the instructions here: - http://wiki.qgis.org/qgiswiki/Building_QT_4_with_Visual_C%2B%2B_2005 + http://wiki.qgis.org/qgiswiki/Building_QT_4_with_Visual_C%2B%2B_2005 - 7.2.4. Proj.4 - ============= + 7.2.4. Proj.4 + ============= Get proj.4 source from here: - http://proj.maptools.org/ + http://proj.maptools.org/ Using the Visual Studio command prompt (ensures the environment is setup properly), run the following in the src directory: @@ -1617,17 +1581,17 @@ Install by running the following in the top level directory setting PROJ_DIR as This can also be added to a batch file. - 7.2.5. GSL - ========== + 7.2.5. GSL + ========== Get gsl source from here: - http://david.geldreich.free.fr/downloads/gsl-1.9-windows-sources.zip + http://david.geldreich.free.fr/downloads/gsl-1.9-windows-sources.zip Build using the gsl.sln file - 7.2.6. GEOS - =========== + 7.2.6. GEOS + =========== Get geos from svn (svn checkout http://svn.refractions.net/geos/trunk geos). Edit geos\source\makefile.vc as follows: @@ -1662,8 +1626,8 @@ Run the following in top level directory, setting GEOS_DIR as appropriate: This can also be added to a batch file. - 7.2.7. GDAL - =========== + 7.2.7. GDAL + =========== Get gdal from svn (svn checkout https://svn.osgeo.org/gdal/branches/1.4/gdal gdal). @@ -1682,37 +1646,37 @@ and - 7.2.8. PostGIS - ============== + 7.2.8. PostGIS + ============== Get PostGIS and the Windows version of PostgreSQL from here: - http://postgis.refractions.net/download/ + http://postgis.refractions.net/download/ Note the warning about not installing the version of PostGIS that comes with the PostgreSQL installer. Simply run the installers. - 7.2.9. Expat - ============ + 7.2.9. Expat + ============ Get expat from here: - http://sourceforge.net/project/showfiles.php?group_id=10127 + http://sourceforge.net/project/showfiles.php?group_id=10127 You'll need expat-win32bin-2.0.1.exe. Simply run the executable to install expat. - 7.2.10. CMake - ============= + 7.2.10. CMake + ============= Get CMake from here: - http://www.cmake.org/HTML/Download.html + http://www.cmake.org/HTML/Download.html You'll need cmake--win32-x86.exe. Simply run this to install CMake. - 7.3. Building QGIS with CMAKE - ============================= + 7.3. Building QGIS with CMAKE + ============================= Get QGIS source from svn (svn co https://svn.osgeo.org/qgis/trunk/qgis qgis). @@ -1753,8 +1717,8 @@ yet. Tim Sutton, 2007 - 8.1. System preparation - ======================= + 8.1. System preparation + ======================= I started with a clean XP install with Service Pack 2 and all patches applied. I have already compiled all the dependencies you need for gdal, expat etc, @@ -1776,8 +1740,8 @@ before we begin: * Create setup.exe installer for QGIS - 8.2. Install the libraries archive - ================================== + 8.2. Install the libraries archive + ================================== Half of the point of this section of the MSVC setup procedure is to make things as simple as possible for you. To that end I have prepared an @@ -1806,8 +1770,8 @@ should adjust any instructions that follow if you plan to do things differently. - 8.3. Install Visual Studio Express 2005 - ======================================= + 8.3. Install Visual Studio Express 2005 + ======================================= First thing we need to get is MSVC Express from here: @@ -1834,8 +1798,8 @@ It will need to download around 90mb of installation files and reports that the install will consume 554mb of disk space. - 8.4. Install Microsoft Platform SDK2 - ==================================== + 8.4. Install Microsoft Platform SDK2 + ==================================== Go to this page: @@ -1970,8 +1934,8 @@ The notes go on to show how to build a mswin32 application which you can try if I'm not going to recover that here. - 8.5. Edit your vsvars - ===================== + 8.5. Edit your vsvars + ===================== Backup your vsvars32.bat file in @@ -2026,8 +1990,8 @@ and replace it with this one: - 8.6. Environment Variables - ========================== + 8.6. Environment Variables + ========================== Right click on 'My computer' then select the 'Advanced' tab. Click environment variables and create or augment the following '''System''' variables (if they dont already exist): @@ -2055,8 +2019,8 @@ create or augment the following '''System''' variables (if they dont already exi - 8.7. Building Qt4.3.2 - ===================== + 8.7. Building Qt4.3.2 + ===================== You need a minimum of Qt 4.3.2 here since this is the first version to officially support building the open source version of Qt for windows under MSVC. @@ -2074,8 +2038,8 @@ Unpack the source to - 8.7.1. Compile Qt - ================= + 8.7.1. Compile Qt + ================= Open the Visual Studio C++ command line and cd to c:\Qt\4.x.x where you extracted the source and enter: @@ -2095,8 +2059,8 @@ can probably ignore that. Just check in c:\Qt\4.3.2\bin to check all dlls and helper apps (assistant etc) have been made. - 8.7.2. Configure Visual C++ to use Qt - ===================================== + 8.7.2. Configure Visual C++ to use Qt + ===================================== After building configure the Visual Studio Express IDE to use Qt: @@ -2146,14 +2110,14 @@ feel free to add some - I just needed QString and took the first hit in google I could find. - 8.8. Install Python - =================== + 8.8. Install Python + =================== Download http://python.org/ftp/python/2.5.1/python-2.5.1.msi and install it. - 8.9. Install SIP - ================ + 8.9. Install SIP + ================ Download http://www.riverbankcomputing.com/Downloads/sip4/sip-4.7.1.zip and extract it into your c:\dev\cpp directory. @@ -2166,8 +2130,8 @@ From a Visual C++ command line cd to the directory where you extract SIP and run - 8.10. Install PyQt4 - =================== + 8.10. Install PyQt4 + =================== Download http://www.riverbankcomputing.com/Downloads/PyQt4/GPL/PyQt-win-gpl-4.3.1.zip and extract it into your c:\dev\cpp directory. @@ -2180,8 +2144,8 @@ From a Visual C++ command line cd to the directory where you extracted PyQt4 and - 8.11. Install CMake - =================== + 8.11. Install CMake + =================== Download and install cmake 2.4.7 or better, making sure to enable the option @@ -2191,8 +2155,8 @@ option - 8.12. Install Subversion - ======================== + 8.12. Install Subversion + ======================== You '''must''' install the command line version if you want the CMake svn scripts to work. Its a bit tricky to find the correct version on the subversion download site as they have @@ -2215,8 +2179,8 @@ And then add To your path. - 8.13. Initial SVN Check out - =========================== + 8.13. Initial SVN Check out + =========================== Open a cmd.exe window and do: @@ -2245,8 +2209,8 @@ At this point you will probably get a message like this: Press 'p' to accept and the svn checkout will commence. - 8.14. Create Makefiles using cmakesetup.exe - =========================================== + 8.14. Create Makefiles using cmakesetup.exe + =========================================== I wont be giving a detailed description of the build process, because the process is explained in the first section (where you manually build @@ -2288,8 +2252,8 @@ Once the build completes right click on INSTALL in the solution browser and choose build. This will by default install qgis into c:\program files\qgisX.X.X. - 8.15. Running and packaging - =========================== + 8.15. Running and packaging + =========================== To run QGIS you need to at the minimum copy the dlls from c:\dev\cpp\qgislibs-release\bin into the c:\program files\qgisX.X.X directory. diff --git a/doc/INSTALL.t2t b/doc/INSTALL.t2t index b9302effdd9..7bc1e1983bf 100644 --- a/doc/INSTALL.t2t +++ b/doc/INSTALL.t2t @@ -8,6 +8,8 @@ Building QGIS from source - step by step %! preproc : TUT_URL https://qgis.org %! PostProc(html): '(?i)(
)' '
\1'
 %! PostProc(html): '(?i)(
)' '\1' +% Next line will replace tabs with 2 spaces in txt generated outputs +%! PostProc(txt): '(?i)(\t)' ' ' %! encoding: iso-8859-1 % These are comments and will not be generated in any output % ------------------- @@ -64,6 +66,11 @@ and getting involved in the project further. /!\ ***Note to document writers:*** Please use this document as the central place for describing build procedures. Please do not remove this notice. +/!\ ***Note to document writers:*** This documented is generated from +doc/INSTALL.t2t - if you need to edit this document, be sure to edit that +file rather than the generated INSTALL document found in the root of the +source directory. + /!\ ***Note:*** This is a 'cut and paste' tutorial - in most cases you can simply copy the commands listed in codeblocks that look like this: