diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/dev/index.rst | 114 | ||||
| -rw-r--r-- | doc/index.rst | 5 | ||||
| -rw-r--r-- | doc/user/index.rst | 6 |
3 files changed, 102 insertions, 23 deletions
diff --git a/doc/dev/index.rst b/doc/dev/index.rst index 6932fa9..4382272 100644 --- a/doc/dev/index.rst +++ b/doc/dev/index.rst @@ -1,6 +1,10 @@ +############## Developer docs -============== +############## +This page contains information useful to people wanting to contribute changes to a :term:`patchset`. + +************ Installation ************ @@ -13,7 +17,7 @@ Installation Make sure you have the following dependencies installed: * Python 3 and pip -* Coccinelle (optional) +* Coccinelle (optional, see :ref:`processors`) Installation can be done by cloning this repository and running @@ -23,46 +27,101 @@ Installation can be done by cloning this repository and running This will install any missing Python dependencies automatically as well. -Generating clean patches -************************ +To check if the installation was successful, run: + +.. code:: -In order to generate a clean .patch file, patchtree needs + $ patchtree -h -* the original source tree (either as a folder or .zip file) -* a list of patch files placed in the same structure as the original source tree +************ +Nomenclature +************ -Writing patch sources -********************* +.. glossary:: + target + A directory of files to be modified (e.g. SDK or library releases). + inputs + patchset + A set of files that describe how to change the target source tree(s), placed in the same structure as the original source tree. -.. _config: + patch + A single file (usually ``.patch`` or ``.diff``) that lists changes to make to one specific target directory. -Configuration -************* +********************** +Building clean patches +********************** -.. currentmodule:: patchtree.config +In order to generate clean patches files, patchtree needs -The configuration file is a Python file sourced from ``ptconfig.py`` relative to the current working directory when executing the ``patchtree`` command. -This file can contain arbitrary Python code. -Certain global variables influence the behavior of patchtree when defined. -These variables are the member variables of the :class:`Config` class. +* the (original) :term:`target` source tree (either as a folder or .zip file) +* a set of :term:`inputs` + +The basic syntax of the patchtree CLI is as follows: + +.. code:: none + + $ patchtree TARGET INPUT [INPUT ...] + +.. note:: + + The inputs are interpreted as globs. + +By default, the resulting patch is written to the standard output. +This behavior, along with many other default behaviors can be changed through the command-line arguments (see ``--help``) or the `configuration file <ptconfig_>`_. + +************************ +Writing patchset sources +************************ + +Each patchset source applies to exactly one target source file, and describes any changes that should be made to that file. +When possible, patchset source files should describe changes *semantically* so they can apply to multiple versions of or variations in the target. +Patchtree allows you to do using a combination of :ref:`processors <processors>` and :ref:`diff engines <diffs>`. + +Every patchset source is first processed by 0 or more processors. +These are indicated using the hash symbol (``#``) in the filename, and each process the input's contents sequentially from right to left. +After processing, the resulting file content is compared to the target source's content using a diff engine. +The diff engine is selected based on the file extension. + +Example: + +.. code:: none + + file extension (.c) + /\ + sdk/middleware/adapters/src/ad_crypto.c#cocci#jinja + \_____________________________________/\__________/ + target source file path processors + (jinja -> cocci) + +.. _processors: Processors -********** +========== -.. currentmodule:: patchtree.process +Processors transform the input's content before it is compared to the target file's content. +They can be chained, and are applied in reverse order (i.e. from right to left) from how they appear in the filename. +Each processor has access to the global :any:`Context` instance, the target file's content, and the (possibly processed) input's content. The processors included with patchtree are listed below. -Custom processors can be created by inheriting from the base :py:class:`Process` class and registering through the `configuration file <config_>`_. .. toctree:: :maxdepth: 1 processor.rst +Custom processors can be created by inheriting from the base :any:`Process` class and registering through the `configuration file <ptconfig_>`_'s :any:`processors <Config.processors>` value. + +.. _diffs: + Diff engines -************ +============ + +Diff engines dictate how the diff delta is calculated from the (possibly processed) input and the target file's content. + +.. TODO: Diff engines are stupid, merge strategies can just as well be handled + by processors since they have access to the appropriate state and variables The diff engines included with patchtree are listed below. @@ -70,3 +129,16 @@ The diff engines included with patchtree are listed below. :maxdepth: 1 diff.rst + +Similar to processors, custom diff engines can be created by inheriting from the base :any:`Diff` class and registering through the `configuration file <ptconfig_>`_'s :any:`diff_strategies <Config.diff_strategies>` value. + +.. _ptconfig: + +****************** +Configuration file +****************** + +The configuration file is a Python file sourced from ``ptconfig.py`` relative to the current working directory when executing the ``patchtree`` command. +This file can contain arbitrary Python code. +Certain global variables influence the behavior of patchtree when defined. +These variables are the member variables of the :any:`Config` class. diff --git a/doc/index.rst b/doc/index.rst index 8390160..aa92c9f 100644 --- a/doc/index.rst +++ b/doc/index.rst @@ -1,7 +1,8 @@ .. include:: ../readme.rst -Usage -***** +############# +Documentation +############# .. toctree:: :maxdepth: 2 diff --git a/doc/user/index.rst b/doc/user/index.rst index 2d311c6..fdca7bd 100644 --- a/doc/user/index.rst +++ b/doc/user/index.rst @@ -1,6 +1,9 @@ +========= User docs ========= +This page contains information useful to people who want to use the .patch files generated by patchtree. + .. note:: By convention, the patch file should be placed in the root of the target directory under the filename ``.patchtree.diff``. @@ -12,6 +15,7 @@ User docs Patches produced by patchtree contain *extended header lines* which are be interpreted by ``git apply``. Because these header lines must include the path to each modified file relative to the repository root, any files which don't exist at the expected location will be skipped silently by ``git``. +**************** Applying a patch **************** @@ -21,6 +25,7 @@ To apply the patch, run the following command in the target directory:: $ git apply .patchtree.diff +***************** Reverting a patch ***************** @@ -28,6 +33,7 @@ To revert the changes of a patch, run the following command in the target direct $ git apply --reverse .patchtree.diff +***************** Upgrading a patch ***************** |