On Fri, Aug 30, 2019 at 03:36:37PM +0200, Roland Hieber wrote: > Remind the reader to upstream their patches, mention the layer > mechanism for search order, fix the logical structure of the whole > chapter by removing the superfluous "Creating Patches for a Package" > header, mention why `--git` can break packages, and general > proof-reading and typo correction. > > Signed-off-by: Roland Hieber <r...@pengutronix.de> > --- > doc/dev_manual.rst | 44 ++++++++++++++++++++++++++++---------------- > 1 file changed, 28 insertions(+), 16 deletions(-) > > diff --git a/doc/dev_manual.rst b/doc/dev_manual.rst > index d79ebdba780d..5dcad97d4a6c 100644 > --- a/doc/dev_manual.rst > +++ b/doc/dev_manual.rst > @@ -494,7 +494,7 @@ At this stage things can fail: > > If the ``configure`` script is not cross compile aware, we are out of > luck. We must patch the source archive in this case to make it work. > -Refer to section :ref:`configure_rebuild` on how to use > +Refer to the section :ref:`configure_rebuild` on how to use > PTXdist’s features to simplify this task. > If the package depends on external components, these components might > be already part of PTXdist. In this case we just have to add this > @@ -1255,15 +1255,27 @@ There can be various reasons why a package must be > patched: > > - or anything else (this case is the most common one) > > -PTXdist handles patching automatically. After extracting the archive, > -PTXdist checks for the existence of a patch directory with the same name > -as the package. If our package’s name is ``foo-1.1.0``, PTXdist searches > -for patches in: > +Ideally, those problems should be adressed in the original project, > +so any patches you add to your BSP or to PTXdist should also be submitted > upstream. > +The upstream project can often provide better feedback, they can integrate > your > +patch into a new release, and also maintain your changes as part of the > project. > +This way we make sure that all advantages of the open source idea work for > us; > +and your patch can be removed again later when a new release of the project > is > +integrated into your BSP or into PTXdist. > + > +PTXdist handles patching automatically. > +After extracting the archive of a package, PTXdist checks for the existence > of > +a patch directory named like its `<PKG>` variable. > +Take an exemplary package `foo` with version `1.1.0`: > +The variable `FOO` will have the value ``foo-1.1.0``, so PTXdist will look > for > +a patch directory named ``foo-1.1.0`` in the following locations: > > #. project (``./patches/foo-1.1.0``) > > #. platform (``./configs/|ptxdistPlatformConfigDir|/patches/foo-1.1.0``) > > +#. the base layer (see :ref:`layers-in-ptxdist`) > +
Hmmm, there can be zero to N layers. Maybe "all other layers (see ...)" > #. ptxdist (``<ptxdist/installation/path>/patches/foo-1.1.0``) > > The patches from the first location found are used. Note: Due to this > @@ -1272,9 +1284,6 @@ PTXdist installation. This can be useful if a project > sticks to a > specific PTXdist revision but fixes from a more recent revision of > PTXdist should be used. > > -Creating Patches for a Package > -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Maybe use this heading above instead of 'Patching Packages' for the whole section? > - > PTXdist uses the utilities *git*, *patch* or *quilt* to work with > patches or patch series. We recommend *git*, as it can manage patch > series in a very easy way. > @@ -1331,7 +1340,7 @@ Using Git > """"""""" > > Create the patch directory like above for *quilt*, > -but only add an empty series file > +but only add an empty series file: > > .. code-block:: text > > @@ -1352,7 +1361,8 @@ and import the package source as the first commit. > use git to apply patches* in `ptxdist setup` to get this behaviour > as a default for every package. > However, note that this setting is still experimental and can lead to Hmm 'experimental' is not correct any more. Can you change this too? Maybe: However, note that this is a development feature that can lead to unexpected failures - ... > - failures for some packages. > + failures – some packages try to determine if they are being compiled > + from a Git source tree, and behave differently in that case. > > Then you can change into the package build directory > (``platform-<name>/build-target/foo-1.1.0``), > @@ -1367,8 +1377,8 @@ The Git history should now look something like this: > * 65a360c2bd60 strfry.c: frobnicate the excusator > * fdc315f6844c (tag: foobar-1.1.0, tag: base) initial commit > > -Finally, call ``git ptx-patches`` to regenerate the patch series in the > -``patches/foo-1.1.0`` folder. > +Finally, call ``git ptx-patches`` to transform those Git commits into the > patch > +series in the ``patches/foo-1.1.0`` folder. > This way they don't get lost when cleaning the package. > > .. note:: PTXdist will only create a Git repository for packages with > @@ -1379,7 +1389,7 @@ This way they don't get lost when cleaning the package. > > Both approaches (Git and quilt) are not suitable for modifying files > that are autogenerated in autotools-based buildsystems. > -Refer to section :ref:`configure_rebuild` on how PTXdist can > +Refer to the section :ref:`configure_rebuild` on how PTXdist can > handle this special task. > > Adding More Patches to a Package > @@ -1393,17 +1403,17 @@ installation directories, NEVER, NEVER, NEVER). Due > to the search order > in which PTXdist searches for patches for a specific package, we can > copy the global patch series to our local project directory. Now we have > the permissions to add more patches or modify the existing ones. Also > -*quilt* is our friend here to manage the patch series. > +*quilt* and *Git* are our friends here to manage the patch series. Lowercase 'git' here, I think. We refer to the command-line tool here. Michael > > If we think that our new patches are valuable also for others, or they > fix an error, it could be a good idea to send these patches to PTXdist > -mainline. > +mainline, and to the upstream project too. > > > .. _configure_rebuild: > > Modifying Autotoolized Packages > -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ > +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ > > Autotoolized packages are very picky when automatically generated files > get patched. The patch order is very important in this case and > @@ -1631,6 +1641,8 @@ convenient way to crate simple templates. It is also > possible to create > more files. For examples, the builtin ``genimage`` template creates a extra > config file for the new package. > > +.. _layers-in-ptxdist: > + > Layers in PTXdist > ----------------- > > -- > 2.23.0 > > > _______________________________________________ > ptxdist mailing list > ptxdist@pengutronix.de -- Pengutronix e.K. | | Industrial Linux Solutions | http://www.pengutronix.de/ | Peiner Str. 6-8, 31137 Hildesheim, Germany | Phone: +49-5121-206917-0 | Amtsgericht Hildesheim, HRA 2686 | Fax: +49-5121-206917-5555 | _______________________________________________ ptxdist mailing list ptxdist@pengutronix.de
