Porters Handbook section 4.4

[Matthew Seaman]

On 26/09/2017 07:38, Russell Haley wrote:
> 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.

Could you add some cautionary notes about the impact of using 'make
makepatch' alongside the technique of using replaceable tokens like
%%PREFIX%%  with a sed command in the post-patch: target?  'make
makepatch' applied blindly will tend to expand all the replaceable
tokens in the generated patch files.  It's something that's quite easy
to do unintentionally.

	Cheers,

	Matthew


-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 931 bytes
Desc: OpenPGP digital signature
URL: <http://lists.freebsd.org/pipermail/freebsd-doc/attachments/20170926/06620ddb/attachment.sig>