Porters Handbook section 4.4

[Kubilay Kocak]

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