From 05ed84e7a9ffe3cd16eefa2be4eadb937324cd6d Mon Sep 17 00:00:00 2001 From: lara Date: Tue, 13 Aug 2024 15:00:10 +0200 Subject: [PATCH] make seperate page for patches --- docs/patches.md | 90 ++++++++++++++++++++++++++++++++ docs/writing-easyconfig-files.md | 85 +----------------------------- mkdocs.yml | 1 + 3 files changed, 92 insertions(+), 84 deletions(-) create mode 100644 docs/patches.md diff --git a/docs/patches.md b/docs/patches.md new file mode 100644 index 000000000..e94ace60b --- /dev/null +++ b/docs/patches.md @@ -0,0 +1,90 @@ +# Patches + +## What are Patches? + +A patch is a file that can be used to modify an existing software sources. This is ofter used to fix bugs, but can also be usedd to improve the usibility or performance. + +## Including patches in the EasyBuild EasyConfigs + +Patches can be provided via the `patches` easyconfig parameter (list). A +patch can be defined as: + +- a `string`, +- a `tuple` of 2 elements, or +- a `dict` + +The most straight-forward use-case is `string`, which contains the name +of the patch file (and must have `.patch` extension). + +A `tuple` adds the possibility to specify where patch should be applied. +This is mostly needed if a patch file adds new files or it is generally +not possible to determine the starting directory. The first element is +the patch file and the second is either the patch level (as an integer) +which is used in the patch command (`patch -p`) or a directory +relative to the unpacked source dir. + +!!! note + `tuple` also has a special use case if the patch file has any other extension than `.patch`. + In this case, the first tuple argument is a file which should be + copied to the unpacked source dir and the second tuple argument is + the target path, where the files should be copied to (relative to + the unpacked source dir). See below for an example of this use case. + +A `dict` adds the ability to pass the `patch` command additional +arguments. For example, the `--binary` flag is needed to patch files +with CRLF endings. The `dict` has a required `filename` key, with +`level` and `opts` being optional ones. + +!!! note + Specifying only `filename` in `dict` is the same as using a plain `string` definition. + Specifying `filename` and `level` is same as using a `tuple` + definition. + +Example: + +``` python +patches = [ + # a simple patch file + 'name-versions-fix.patch', + + # when creating only new files by patch file, you need to specify the level: + ('name-versions-fix.patch', 1), + + # apply the patch in a (sub-)subdirectory inside the source tree + ('name-versions-fix.patch', 'src/subfolder'), + + # copy file to target_path folder + ('Makefile', 'target_path'), + + # specify patch file and optionally level and opts for patch command + {'filename': 'name-versions-fix.patch', 'level': 1, 'opts': '-l'} +] +``` + +## Creating a patch file + +Get the sources which you would like to patch. And create a copy to be able to create a diff file. + +``` bash +cp -a .orig + +``` + +Than you can make the necessary changes to the sources in the `` that are not marked with the `.orig` extension. Once you have made all the updates to the sources you can create the `.patch` file with `diff`. + +``` bash +diff -ruN .orig > -_.patch +``` + +Please also add a description on top of the patch file and the author or source of the patch. + +For example: + +``` +minimus2 needs delta-filter and show-coords but these were not set correctly like NUCMER +author: Lara Peeters (HPC-UGent) +diff -ru amos-3.1.0.orig/src/Pipeline/Makefile.in amos-3.1.0/src/Pipeline/Makefile.in +--- amos-3.1.0.orig/src/Pipeline/Makefile.in 2011-08-05 05:08:07.000000000 +0200 ++++ amos-3.1.0/src/Pipeline/Makefile.in 2024-03-14 12:31:16.218067000 +0100 +@@ -477,7 +477,8 @@ +``` diff --git a/docs/writing-easyconfig-files.md b/docs/writing-easyconfig-files.md index 353282bd2..6951c02e9 100644 --- a/docs/writing-easyconfig-files.md +++ b/docs/writing-easyconfig-files.md @@ -130,7 +130,7 @@ Remarks: - patches need to be EasyBuild-compatible - unified diff format (`diff -ruN`) - patched locations relative to unpacked sources -- see [Patches][common_easyconfig_param_sources_patches] for more information on `patches` +- see [Patches][patches] for more information on `patches` - see [Checksums][common_easyconfig_param_sources_checksums] for more information on `checksums` - `sources` is usually specified as a list of strings representing filenames for source files, but other formats are supported too, see @@ -160,89 +160,6 @@ checksums = ['ac7534163a09e21a5fa763e4e16dfc119bc84043f6e6a807aba666518f8df440'] a string template `%(version)s` can be used, see also [Dynamic values for easyconfig parameters][easyconfig_param_templates]. -#### Patches {: #common_easyconfig_param_sources_patches } - -Patches can be provided via the `patches` easyconfig parameter (list). A -patch can be defined as: - -- a `string`, -- a `tuple` of 2 elements, or -- a `dict` - -The most straight-forward use-case is `string`, which contains the name -of the patch file (and must have `.patch` extension). - -A `tuple` adds the possibility to specify where patch should be applied. -This is mostly needed if a patch file adds new files or it is generally -not possible to determine the starting directory. The first element is -the patch file and the second is either the patch level (as an integer) -which is used in the patch command (`patch -p`) or a directory -relative to the unpacked source dir. - -!!! note - `tuple` also has a special use case if the patch file has any other extension than `.patch`. - In this case, the first tuple argument is a file which should be - copied to the unpacked source dir and the second tuple argument is - the target path, where the files should be copied to (relative to - the unpacked source dir). See below for an example of this use case. - -A `dict` adds the ability to pass the `patch` command additional -arguments. For example, the `--binary` flag is needed to patch files -with CRLF endings. The `dict` has a required `filename` key, with -`level` and `opts` being optional ones. - -!!! note - Specifying only `filename` in `dict` is the same as using a plain `string` definition. - Specifying `filename` and `level` is same as using a `tuple` - definition. - -Example: - -``` python -patches = [ - # a simple patch file - 'name-versions-fix.patch', - - # when creating only new files by patch file, you need to specify the level: - ('name-versions-fix.patch', 1), - - # apply the patch in a (sub-)subdirectory inside the source tree - ('name-versions-fix.patch', 'src/subfolder'), - - # copy file to target_path folder - ('Makefile', 'target_path'), - - # specify patch file and optionally level and opts for patch command - {'filename': 'name-versions-fix.patch', 'level': 1, 'opts': '-l'} -] -``` - -##### Creating a patch file - -Get the sources which you would like to patch. And create a copy to be able to create a diff file. - -``` bash -cp -a .orig - -``` - -Than you can make the necessary changes to the sources in the `` that are not marked with the `.orig` extension. Once you have made all the updates to the sources you can create the `.patch` file with `diff`. - -``` bash -diff -ruN .orig > -_.patch -``` - -Please also add a discription on top of the patch file and the author or source of the patch. - -For example: -``` -minimus2 needs delta-filter and show-coords but these were not set correctly like NUCMER -author: Lara Peeters (HPC-UGent) -diff -ru amos-3.1.0.orig/src/Pipeline/Makefile.in amos-3.1.0/src/Pipeline/Makefile.in ---- amos-3.1.0.orig/src/Pipeline/Makefile.in 2011-08-05 05:08:07.000000000 +0200 -+++ amos-3.1.0/src/Pipeline/Makefile.in 2024-03-14 12:31:16.218067000 +0100 -@@ -477,7 +477,8 @@ -``` #### Checksums {: #common_easyconfig_param_sources_checksums } diff --git a/mkdocs.yml b/mkdocs.yml index 418c48878..287c4389a 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -83,6 +83,7 @@ nav: - Local variables in easyconfigs: easyconfig-files-local-variables.md - Unit tests: unit-tests.md - Framework Overview: framework-overview.md + - Patches: patches.md - Experimental features: - (overview): experimental-features.md - Creating container images/recipes: containers.md