diff options
Diffstat (limited to 'doc/dev')
| -rw-r--r-- | doc/dev/index.rst | 114 |
1 files changed, 93 insertions, 21 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. |