How To Help Developing Lazarus: what changed
Revision 3 to 4. Removed lines have a minus sign; added lines have a plus sign.
| Old | New | Line | |
|---|---|---|---|
| 1 | 1 | ## Prerequisites to developing Lazarus | |
| 2 | 2 | ||
| 3 | 3 | There are two things to note: | |
| 4 | 4 | ||
| 5 | 5 | - You should have the latest release of the Free Pascal compiler (FPC) **or** a more recent GIT version of it (ie development version). For obtaining FPC, see [Free Pascal download](http://www.freepascal.org/download.var) for the latest release version **or** [[Installing the Free Pascal Compiler]] for building a development version from source. | |
| 6 | 6 | ||
| 7 | 7 | - You **must** have the very latest Lazarus development version from the GIT repository. For obtaining the latest version, see [[Getting Lazarus|Getting Lazarus from the GitLab server]]. | |
| 8 | 8 | ||
| 9 | 9 | ## Development areas | |
| 10 | 10 | ||
| 11 | 11 | So now you have the latest version of Lazarus and wish to start improving it, but are asking yourself "where do I begin?" Well, that depends. | |
| 12 | 12 | ||
| 13 | 13 | ### Known bugs | |
| 14 | 14 | ||
| 15 | 15 | If you don't have any particular woes about Lazarus but just want to help, then I would recommend looking at the bug list [Bug Tracker](http://bugs.freepascal.org/set_project.php?project_id=1) find a bug that you think you can fix, and start hacking. Additional information on submitting bug reports and using the bug tracker can be found at [[How do I create a bug report]]. | |
| 16 | 16 | ||
| 17 | 17 | ### Documentation | |
| 18 | 18 | ||
| 19 | 19 | Lazarus needs more documentation! If you don't want to fix a bug you can help by writing documentation. Even this page is a work in progress. If you have useful information to add, or if you see mistakes, please feel free to improve the contents of this page. | |
| 20 | 20 | ||
| 21 | 21 | Look at [[Lazarus Documentation Editor]] and [[LCL Documentation Roadmap]] for some help on how to and a list of units to be documented. | |
| 22 | 22 | ||
| 23 | 23 | The on-line IDE help is gradually being created as a part of the wiki. Recently a lot of stub pages of the [[Lazarus IDE]] documentation about the IDE windows have been added. When working in IDE, if you need help, press F1. You will be presented a help wiki page (possibly empty or incomplete). Improve it, if you have the relevant knowledge. | |
| 24 | 24 | ||
| 25 | 25 | ### IDE | |
| 26 | 26 | ||
| 27 | 27 | See these link: [[Extending the IDE]]. | |
| 28 | 28 | ||
| 29 | 29 | ### Widgetsets ("interfaces") | |
| 30 | 30 | ||
| 31 | 31 | A [[Widgetset|widgetset]] (WS) is the "glue code" between the LCL code parts that are independent of the target operating system and the target operating system itself. For each supported target OS, the corresponding WS units are to be found in one of the subdirectories under the C:\Lazarus\lcl\interfaces\\. | |
| 32 | 32 | ||
| 33 | 33 | Here is an outline of the steps one should follow, in order to improve a widgetset (description provided by Mattias Gärtner on the Lazarus mailing list on 2006-07-15). When making changes to a WS, it is not necessary to rebuild everything (Lazarus including the IDE), in order to test the efects of the changes. Proceed as follows:\ | |
| 34 | 34 | ||
| 35 | - | ||
| 36 | - | ||
| 37 | - | ||
| 38 | - | ||
| 39 | - | ||
| 40 | - | ||
| 41 | - | ||
| 42 | - | ||
| 43 | - | ||
| 44 | - | ||
| 45 | - | ||
| 46 | - | ||
| 47 | - | ||
| 48 | - | ||
| 49 | - | ||
| 50 | - | ||
| 51 | - | ||
| 52 | - | ||
| 35 | + | ``` pascal | |
| 36 | + | * Create your testbed project (a small program | |
| 37 | + | which should contain the testing code for your WS changes); | |
| 38 | + | * Setup the keyboard shortcuts for 'Build Lazarus' and 'Configure Build Lazarus' | |
| 39 | + | (in IDE, go to Editor Options/Keymapping); | |
| 40 | + | <u>repeat</u> | |
| 41 | + | * build your application (this will re-build the WS you altered, and will re-build the LCL); | |
| 42 | + | <u>repeat</u> | |
| 43 | + | * Make your improvement in the WS code; | |
| 44 | + | * Build Lazarus (in IDE, go to Tools/Build Lazarus | |
| 45 | + | - this only rebuilds the LCL, which rebuilds also the selected WS); | |
| 46 | + | * Now compile your testbed project; | |
| 47 | + | * Run and debug your program; | |
| 48 | + | <u>until</u> no errors are found in your change; | |
| 49 | + | * Reconfigure "Build Lazarus" to build all | |
| 50 | + | (in IDE, go again to Tools/Configure "Build Lazarus"); | |
| 51 | + | * Build Lazarus and test the IDE; | |
| 52 | + | <u>until</u> no errors/degradation due to your changes are found in IDE; | |
| 53 | + | * Create a patch and send it (see further below for details). | |
| 54 | + | ``` | |
| 53 | 55 | ||
| 54 | 56 | ## How to submit your changes? | |
| 55 | 57 | ||
| 56 | 58 | You will need to make a "patch" (see [[Creating A Patch]]). The preferred way of submitting the patch to the Lazarus developers is to create an issue in the bug tracker and attach the patch to it. | |
| 57 | 59 | ||
| 58 | 60 | ## Dealing with regressions | |
| 59 | 61 | ||
| 60 | 62 | From time to time changes in the Lazarus source code might cause features which worked before to stop working. In a case where there is no clue as to what caused the break it may be useful to do an iteration method to determine exactly which revision caused the problem. | |
| 61 | 63 | ||
| 62 | 64 | This process is simple, although somewhat time consuming: | |
| 63 | 65 | ||
| 64 | 66 | Suppose it works with rev 1000 and not with 5000. Then test with 3000. Testing requires updating the svn code, rebuilding the LCL for the desired widgetset, rebuilding a test application which uses the feature and testing this application. If it works, repeat with 3000 and 5000 as extremes. If not, use 1000 and 3000 as extremes. | |
| 65 | 67 | ||
| 66 | 68 | After some time you should be able to isolate which revision broke it. This information makes fixing the problem much easier, so we encourage people helping to develop Lazarus to try this process and post this information in bug reports in case there are any regressions with no clear clue of what went wrong. | |
| 67 | 69 | ||
| 68 | 70 | To check to which data each revision corresponds, one can use the [Lazarus svn browser (ViewVC)](http://svn.freepascal.org/cgi-bin/viewvc.cgi/?root=lazarus). After the interval of revisions has been reduced to a relatively small number, like 25 or so, it may be quicker to check the revisions with ViewVC and check which are possible candidates for the break, to speed up the final part. | |
| 69 | 71 | ||
| 70 | 72 | One can obtain a particular revision using the command: | |
| 71 | 73 | ||
| 72 | - | ||
| 74 | + | ```text | |
| 75 | + | svn update -r <revision number> | |
| 76 | + | ``` | |
| 73 | 77 | ||
| 74 | 78 | **A word of caution.** If you have a slow and unreliable internet connection (like modem dial-up or 3G) and limited bandwidth, then checking out various revisions from SubVersion is a slow and costly process. Every revision you checkout has to be downloaded from the internet. | |
| 75 | 79 | ||
| 76 | 80 | This issue is completely eliminated if you use Git, because the whole repository history is local on your computer. So you can checkout any older revisions without needing an internet connection and checkouts are instant. | |
| 77 | 81 | ||
| 78 | 82 | ### Automate searching for regression errors | |
| 79 | 83 | ||
| 80 | 84 | #### SubVersion | |
| 81 | 85 | ||
| 82 | 86 | Florian wrote a small Unix script which can help automate the process of finding a regression error. The script is called [searchrev](http://svn.freepascal.org/cgi-bin/viewvc.cgi/scripts/florian/unix/searchrev?view=markup&root=fpcbuild). | |
| 83 | 87 | ||
| 84 | 88 | There are command-line tools inspired by "git-bisect". A Unix shell script can be found in Debian-based Linux distributions as part of *subversion-tools* package. A Perl-based version can be found in some other Linux distributions (eg. SuSE, Fedora, CentOS) as *svn-bisect* package or [here](https://github.com/Infinoid/svn-bisect). | |
| 85 | 89 | ||
| 86 | 90 | #### Git mirrors | |
| 87 | 91 | ||
| 88 | 92 | Git includes a command called *bisect* which helps with finding regression bugs. It also has built-in support for automated testing. You need to create a small testcase and let Git use that testcase to determine if a revision is buggy or not. So with the automated bisecting, regression bugs can be found in seconds. For more information on the *git bisect* command, see the [Git User Manual](http://www.kernel.org/pub/software/scm/git/docs/user-manual.html#using-bisect). | |
| 89 | 93 | ||
| 90 | 94 | ## Need more help? | |
| 91 | 95 | ||
| 92 | 96 | If you have any question you can ask them on one of the following places: | |
| 93 | 97 | ||
| 94 | 98 | - The Free Pascal mailing lists: [<http://www.freepascal.org/maillist.var>](http://www.freepascal.org/maillist.var) | |
| 95 | 99 | - The Lazarus Mailing lists [<http://lists.lazarus.freepascal.org/mailman/listinfo>](http://lists.lazarus.freepascal.org/mailman/listinfo) | |
| 96 | 100 | - The [Lazarus Forum](http://forum.lazarus.freepascal.org) | |
| 97 | 101 | - The [Lazarus Developer's blog](http://lazarus-dev.blogspot.de) | |
| 98 | 102 | ||
| 99 | 103 | ## See also | |
| 100 | 104 | ||
| 101 | 105 | - [[Creating A Patch]] If you have modified the source code to implement a solution, this article helps you to add it to your bug report in the most efficient way, so that developers can add it to the main code as fast as possible | |
| 102 | 106 | - [[Database bug reporting]] Specific info and sample programs for database bugs | |
| 103 | 107 | - [[How do I create a bug report]] general information on submitting bugs, what should be covered in a bug report, and using the bug tracker. | |
| 104 | 108 | - [[Moderating the bug tracker]] | |
| 105 | 109 | - [[Lazarus Development Process]] | |
| 106 | 110 | ||
| 107 | 111 | --- | |
| 108 | 112 | *From the Free Pascal wiki, page "How To Help Developing Lazarus", as it stood on 2023-04-19 after a change by Xhajt03, out of the wiki's dump of 2024-05-26. Copyright stays with the author who wrote it, according to the old wiki's [[Licensing]] page. If you have concerns about this material, [message the admin](/wiki-contact).* | |
| 109 | 113 | Category: Community | |
| 110 | 114 | Category: Debugging | |
| 111 | 115 | Category: FPC Issues | |
| 112 | 116 | Category: Lazarus |