Difference between revisions of "Creating A Patch"

From Lazarus wiki
Jump to navigationJump to search
m (→‎Creating a patch using Git: Remove defunct git-svn note reference)
 
(91 intermediate revisions by 17 users not shown)
Line 1: Line 1:
 
{{Creating A Patch}}
 
{{Creating A Patch}}
==Instructions==
 
This assumes you have gotten Lazarus from SVN. [[Getting Lazarus#Via SVN| Getting Lazarus Via SVN]]
 
  
Open a command or cmd prompt and cd to the directory that the Lazarus source exists.
+
If you want to submit improvements to the FPC or Lazarus code, you need to submit a patch which developers can easily merge.
  
'''Instructions For Windows:'''
+
Exceptions:
 +
# .po translation files should be sent as whole files
 +
# new files should be sent as whole files, with instructions where they should be placed
  
We'll assume that you have your SVN checkout of Lazarus in C:\lazarus
+
__TOC__
 +
== Requirements ==
  
# Open a MS-DOS prompt
+
You need the '''main/development''' version of Lazarus (or FPC). You can get Lazarus using either Git or SVN.
# c: {press enter}
+
* Git: [[Getting Lazarus#Getting_Lazarus_from_the_GitLab_server|Getting Lazarus development version]]. This is the native repository.
# cd \lazarus {press enter}
+
* SVN: Read-only mirror of the official GitLab repository requires some svn gymnastics due to a bug in many versions of svn:
# svn diff > mypatch.dif {press enter}
 
  
'''Instructions For Linux/BSD etc:'''
+
svn checkout --depth files https://github.com/fpc/Lazarus/branches all
 +
cd all
 +
svn update --set-depth infinity main
  
We'll assume that you have your SVN checkout of Lazarus in $HOME/lazarus
+
svn checkout --depth files https://github.com/fpc/FPCSource/branches all
 +
cd all
 +
svn update --set-depth infinity main
  
# Open your favorite Terminal program
+
{{Warning|'''If you submit patches, do <u>not</u> base them on stable versions of Lazarus/FPC. Typically the development version is very different from stable versions as many improvements and fixes have been applied by the developers'''}}
# cd $HOME {press enter}
 
# cd lazarus {press enter}
 
# svn diff > mypatch.diff {press enter}
 
  
 +
==Platform differences==
 +
The instructions later assume you have opened a command prompt and moved (cd) to the directory of the repository. Here are the details :
  
''Note: I also like to look the file over to see if there is anything in there that shouldn't be.''
+
===Windows===
 +
Assuming you checked out Lazarus into C:\lazarus, open command prompt (cmd.exe) and type "cd \lazarus".
  
The recommended way to submit a patch is through the [http://www.lazarus.freepascal.org/mantis/ bug tracker]. If there is a report for the issue your patch fixes, use that, otherwise create a new issue. Upload the file to attach it to the issue.
+
===*nix systems===
 +
Assuming you checked out Lazarus into ~/lazarus, open terminal and type "cd ~/lazarus".
  
Alternatively you can zip or gzip the file you have created and email it to the Lazarus mailing list (40 kB limit) or the mailbox for patches [mailto:patch@lazarus.dommelstein.net patch@lazarus.dommelstein.net].  
+
==Creating a patch using SVN==
 +
<syntaxhighlight lang="bash">svn diff > mypatch.diff</syntaxhighlight>
 +
This includes all changed files in the whole SVN repository.
  
That's all!
+
You can also define the individual files, to make sure no garbage is included, eg. :
 +
<syntaxhighlight lang="bash">svn diff ide/main.pp ideintf/objectinspector.pp > mypatch.diff</syntaxhighlight>
  
== Troubleshooting ==
+
{{Note| If using [http://tortoisesvn.tigris.org/ TortoiseSVN] on Windows, you can select the folder where Lazarus was checked out in Windows Explorer then right click to select TortoiseSVN->Create Patch... }}
This mostly applies to Windows but could apply for other platforms as well.
 
  
'''You get the error "svn command not found" or similar.'''
+
See also [[TortoiseSvn#Troubleshooting]] if you have problems.
Most probably you do not have svn.exe in your PATH environment variable. The following steps should fix this problem:
 
  
# Locate svn.exe using the Find Files feature of your Start menu.
+
==Creating a patch using Git==
# Once you have located svn.exe you need to add the directory it is in to your PATH.
+
First, develop your code in a separate branch!
As an example: From the command prompt type:
+
While your development branch is active, you can create patches of all your local commits by :
  set PATH=%PATH%;"C:\Program Files\TortoiseSVN\"
+
<syntaxhighlight lang="bash">git format-patch master</syntaxhighlight>
 +
It creates a set of patches named like "0001-CommitMsg.patch", "0002-CommitMsg.patch" and so on.
  
''Note: Your directory containing svn.exe might not be the same on your computer as the one used in this document. It is used here only as an example.''
+
If you want all the changes in one patch, either combine the commits using "git rebase -i ..." or use the following command :
 +
<syntaxhighlight lang="bash">git format-patch master --stdout > mypatch.patch</syntaxhighlight>
  
 +
==Submitting the patch==
 +
Now you have a patch. I'd suggest to look the file over to see if it looks ok (no unexpected changes).
  
The following is optional:
+
The recommended way to submit a patch is through the [http://bugs.freepascal.org bug tracker], see [[How do I create a bug report]] for details. If there is a report for the issue your patch fixes, use that, otherwise create a new issue. Upload the file to attach it to the issue.
  
'''To make this permanant'''
+
==Git==
 +
The GitHub repository [https://github.com/graemeg/lazarus] is only a mirror and does not accept pull-requests.
  
For Windows98 or lower, you can add the line above (or similar) to your C:\autoexec.bat file near the end.
+
==Applying a patch==
 
+
This explains how to apply somebody else's patch to your local repository. You can test the patch by using the --dry-run toggle switch like this:
For Windows2000 or greater you can add this directory to your PATH by:
+
<syntaxhighlight lang="bash">patch --dry-run < somepatch.diff</syntaxhighlight>
 
+
The output of the patch program will be identical to the actual patching, only it does not alter the sourcecode files. Very handy for testing, without the possibility to screw up your source.
# Right-Clicking on "My Computer"
 
# Select "Properties"
 
# Choose the "Advanced" tab.
 
# Click the "Environment Variables" button.
 
# Locate the "Path" line in "System Variables" and add: ;"C:\Program Files\TortoiseSVN\" to the end.
 
  
''Note: Your directory containing svn.exe might not be the same on your computer as the one used in this document. It is used here only as an example.''
+
===A patch made with "svn diff"===
 +
To do the final patching, use the following commandline:
 +
<syntaxhighlight lang="bash">patch < somepatch.diff</syntaxhighlight>
 +
If that doesn't work because the path layout of your environment is different from the environment where the patch was created, you can tell ''patch'' to strip out all path information:
 +
<syntaxhighlight lang="bash">patch -p0 < somepatch.diff</syntaxhighlight>
  
==Applying a patch==
+
Any GUI tool for diffs on Windows can handle these patches, too, including TortoiseMerge.
To apply a patch is simple. You can test the patch by using the --dry-run toggle switch like this:
 
  
 +
===A patch made with "git format-patch"===
 +
====Git====
 +
Git itself applies the patch like this :
 +
<syntaxhighlight lang="bash">git apply 0001-gitpatch.patch</syntaxhighlight>
  
  patch --dry-run < mypatch.diff
+
====patch====
 +
The "patch" command now supports git format patches with -p1. This is tested with patch v.2.6.1 on Linux, old versions may not support it.
  
 +
<syntaxhighlight lang="bash">patch -p1 < 0001-gitpatch.patch</syntaxhighlight>
  
The output of the patch program will be identical to the actual patching, only it does not alter the sourcecode files. Very handy for testing, without wanting to screw up your source.
+
"patch" is available for Windows, too, but there are also GUI tools for the job.
  
To do the final patching, you use the following commandline:
+
====TortoiseMerge====
 +
TortoiseMerge supports the Git format patch without problems.
 +
It is installed together with Tortoise SVN but is not integrated in explorer. It must be opened from the Start menu.
  
 +
ToDo: add more GUI tools that support Git format patches
  
  patch < mypatch.diff
+
===Troubleshooting===
 +
Finally, patches may have a Unix/Linux line ending (LF) while your local file has Windows (CR+LF) line endings or vice versa. You'll have to convert the patch file before applying on Windows at least, as the supplied patch.exe is picky about line endings.
  
Or, to fix separators:
+
On Windows, the patch.exe supplied with FPC/Lazarus is very picky; you may have better luck with the patch.exe supplied by Git:
 +
<syntaxhighlight lang="dos">"C:\Program Files (x86)\Git\bin\patch.exe" -p0 < mypatch.diff</syntaxhighlight>
 +
... or the svn patch command available since SVN 1.7.
  
  patch -p0 < mypatch.diff
+
==See also==
 +
* [[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.
 +
* [[Tips on writing bug reports]] detailed information on what should be covered in a bug report.
 +
* [[Database bug reporting]] Specific info and sample programs for database bugs
 +
* [[Moderating the bug tracker]]

Latest revision as of 23:02, 13 January 2022

Deutsch (de) English (en) español (es) français (fr) 日本語 (ja) português (pt) русский (ru) slovenčina (sk)

If you want to submit improvements to the FPC or Lazarus code, you need to submit a patch which developers can easily merge.

Exceptions:

  1. .po translation files should be sent as whole files
  2. new files should be sent as whole files, with instructions where they should be placed

Requirements

You need the main/development version of Lazarus (or FPC). You can get Lazarus using either Git or SVN.

  • Git: Getting Lazarus development version. This is the native repository.
  • SVN: Read-only mirror of the official GitLab repository requires some svn gymnastics due to a bug in many versions of svn:
svn checkout --depth files https://github.com/fpc/Lazarus/branches all
cd all
svn update --set-depth infinity main
svn checkout --depth files https://github.com/fpc/FPCSource/branches all
cd all
svn update --set-depth infinity main
Warning-icon.png

Warning: If you submit patches, do not base them on stable versions of Lazarus/FPC. Typically the development version is very different from stable versions as many improvements and fixes have been applied by the developers

Platform differences

The instructions later assume you have opened a command prompt and moved (cd) to the directory of the repository. Here are the details :

Windows

Assuming you checked out Lazarus into C:\lazarus, open command prompt (cmd.exe) and type "cd \lazarus".

*nix systems

Assuming you checked out Lazarus into ~/lazarus, open terminal and type "cd ~/lazarus".

Creating a patch using SVN

svn diff > mypatch.diff

This includes all changed files in the whole SVN repository.

You can also define the individual files, to make sure no garbage is included, eg. :

svn diff ide/main.pp ideintf/objectinspector.pp > mypatch.diff
Light bulb  Note: If using TortoiseSVN on Windows, you can select the folder where Lazarus was checked out in Windows Explorer then right click to select TortoiseSVN->Create Patch...

See also TortoiseSvn#Troubleshooting if you have problems.

Creating a patch using Git

First, develop your code in a separate branch! While your development branch is active, you can create patches of all your local commits by :

git format-patch master

It creates a set of patches named like "0001-CommitMsg.patch", "0002-CommitMsg.patch" and so on.

If you want all the changes in one patch, either combine the commits using "git rebase -i ..." or use the following command :

git format-patch master --stdout > mypatch.patch

Submitting the patch

Now you have a patch. I'd suggest to look the file over to see if it looks ok (no unexpected changes).

The recommended way to submit a patch is through the bug tracker, see How do I create a bug report for details. If there is a report for the issue your patch fixes, use that, otherwise create a new issue. Upload the file to attach it to the issue.

Git

The GitHub repository [1] is only a mirror and does not accept pull-requests.

Applying a patch

This explains how to apply somebody else's patch to your local repository. You can test the patch by using the --dry-run toggle switch like this:

patch --dry-run < somepatch.diff

The output of the patch program will be identical to the actual patching, only it does not alter the sourcecode files. Very handy for testing, without the possibility to screw up your source.

A patch made with "svn diff"

To do the final patching, use the following commandline:

patch < somepatch.diff

If that doesn't work because the path layout of your environment is different from the environment where the patch was created, you can tell patch to strip out all path information:

patch -p0 < somepatch.diff

Any GUI tool for diffs on Windows can handle these patches, too, including TortoiseMerge.

A patch made with "git format-patch"

Git

Git itself applies the patch like this :

git apply 0001-gitpatch.patch

patch

The "patch" command now supports git format patches with -p1. This is tested with patch v.2.6.1 on Linux, old versions may not support it.

patch -p1 < 0001-gitpatch.patch

"patch" is available for Windows, too, but there are also GUI tools for the job.

TortoiseMerge

TortoiseMerge supports the Git format patch without problems. It is installed together with Tortoise SVN but is not integrated in explorer. It must be opened from the Start menu.

ToDo: add more GUI tools that support Git format patches

Troubleshooting

Finally, patches may have a Unix/Linux line ending (LF) while your local file has Windows (CR+LF) line endings or vice versa. You'll have to convert the patch file before applying on Windows at least, as the supplied patch.exe is picky about line endings.

On Windows, the patch.exe supplied with FPC/Lazarus is very picky; you may have better luck with the patch.exe supplied by Git:

"C:\Program Files (x86)\Git\bin\patch.exe" -p0 < mypatch.diff

... or the svn patch command available since SVN 1.7.

See also