Porters Handbook section 4.4

[Russell Haley]

On Mon, Sep 25, 2017 at 11:21 PM, Kubilay Kocak <koobs at freebsd.org> wrote:
> On 9/26/17 2:53 PM, Russell Haley wrote:
>> On Sun, Sep 24, 2017 at 10:02 PM, Kubilay Kocak <koobs at freebsd.org> wrote:
>>> On 9/25/17 2:08 PM, Russell Haley wrote:
>>>> Hi,
>>>>
>>>> Section 4.3 of the porters handbook talks about making modifications
>>>> to a private copy of a tarball and recording the steps.
>>>>
>>>> Section 4.4 talks about changing directories into the affected ports
>>>> dir and running make makepatch to generate patch files.
>>>>
>>>> I am unsure how the makepatch target is supposed to find my private
>>>> directory. Since I was confused, I created patches, added them to the
>>>> port, ran make, then ran make makepatch and the system re-generated
>>>> new "makepatch" patches.
>>>
>>> Quite a number of new users have raised the same question on IRC.
>>>
>>>> So, my question is thus:
>>>>
>>>> To me, section 4.4 seems vague about where changes should be made,
>>>> which is compounded by the information in section 4.3. Can the
>>>> makepatch target ask for and find a private directory, or should the
>>>> handbook be clarified to state that the changes should be made to the
>>>> 'work' folder? If the later is true, I assume there is some proper
>>>> workflow to keep changes from being destroyed while testing?
>>>
>>> The handbook section needs to be updated to be less ambiguous with
>>> regard to where things should be done.
>>>
>>> I'd be happy to provide a docs committer with verbiage if they can help
>>> with formatting/commit.
>> Hi,
>>
>> If you provide the verbiage, I'll attempt a patch. :)
>>
>> Russ
>>
>>>> If there is a section in the handbook clarifying this, please just say
>>>> so and I will go find it.
>>>>
>>>> Thanks!
>>>> Russ
>>>
>>> ./koobs
>
> In section:
>
> 4.4. Patching
>
> - Add new section (at/numbered 4.4.2)
>   - Name: Automatic Patch Generation
> - Renumber sections (4.4.2 -> 4.4.3)
>
> Text:
>
> The ports framework provides a {{{makepatch}} target, which when run,
> automatically creates correctly named and formatted patch files in the
> correct location. The general process is as follows:
>
> % cd <port directory>
> % make patch
>
> Note: In the general case, {{{make patch}} is used (not just {{{make
> extract}}} to extract the DISTFILES), because ports that contain
> existing patches need to have the patches applied so that they are also
> generated (regenerated) in the last step.
>
> ```
> % cd work/<directory> (WRKSRC)
> ```
>
> At this point, make the source changes in WRKSRC:
>
> ```
> % cp <file> <file>.orig
> % edit <file>
> ```
>
> Repeat the above steps for each file at any location within WRKSRC that
> needs a patch file created.
>
> Go back to the main port directory:
>
> ```
> % cd <port directory>
> ```
>
> Finally, run the {{{makepatch}}} target
>
> ```
> % make makepatch
> ```
>
> The makepatch target recursively searches WRKSRC for <file>/<file>.orig
> pairs within WRKSRC, and creates a patch file in PATCHDIR from each pair
> (using diff).
>
> NOTE: Any pre-existing patches in PATCHDIR that are *not* regenerated
> during the above process are placed in a backup location in WRKDIR. This
> backup location is deleted on {{{make clean}}}. This may occur when not
> using {{{make patch}}} to extract the sources, because existing patches
> are or were not applied, or if there are existing patch files that make
> edits to multiple files in a single patch file, which will now be in
> separate patch files after makepatch regeneration. Inspect and review
> the patch files in PATCHDIR to ensure they have been created as expected.
>
> == Other ==
>
> - Patch files are stored in PATCHDIR, usually files/, from where they
> will be automatically applied
> + Patch files are stored in PATCHDIR, by default `files/` in the port
> directory, which are automatically applied in the 'patch' stage

Thanks! I'll play with this on the weekend.

Russ