Page MenuHomeFreeBSD
Differential D12921 Diff 40099 en_US.ISO8859-1/books/porters-handbook/ph-working-with-files/chapter.xml

Changeset View

Standalone View

View Options

en_US.ISO8859-1/books/porters-handbook/ph-working-with-files/chapter.xml

<?xml version="1.0" encoding="iso-8859-1"?>
<!--
The FreeBSD Documentation Project
$FreeBSD: head/en_US.ISO8859-1/books/porters-handbook/porting-why/chapter.xml 50632 2017-08-04 11:34:16Z mat $
-->
<chapter xmlns="http://docbook.org/ns/docbook"
xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0"
xml:id="ph-working-with-files">
<title>Working With Files</title>
<sect1 xml:id="ph-patching">
<title>Using the Built In Patching Tools</title>
<para>
Creating a new port involves generating the port files from scratch or copying an existing, similar port. Maintaining a port involves retrieving the latest revisions of the sources, making changes to those sources, and then extracting those changes as a "meta-patch" for the port. The following sections describe the steps involved in maintaining a patch file, with notes to new port maintainers.
</para>
<sect2 xml:id="ph-work-dir">
<title>The Work Directory</title>
<para>
The work directory is created under the port directory and is used to store "working data". Working data consists of the source files downloaded from the upstream repository, inetermediate build output, as well as the build output itself that can be tested and installed. Source files are downloaded and unpacked to this directory and optionally patched depending on the target. This directory is where you will be performing the majority of your changes to the upstream source files. By using the built in mechanisms and directory structures, you ensure that the tools available can assist in streamlining the update process.
</para>
</sect2>
<sect2 xml:id="working-with-makepatch">
<para>
The ports framework provides a <buildtarget>makepatch</buildtarget>
target, which when run,
automatically creates correctly named and formatted patch files in the
correct location from the modified sources. Here are the steps to maintain a port
</para>
<procedure>
<step>
<para>
First, retrieve the source files and optionally apply patches.
If you wish to preserve or update the existing patches in the port, use the <buildtarget>patch</buildtarget> target. This target retrieves sources and applies all patches in the
<filename>files</filename> directory.
</para>
<para>
If you wish to discard the current patches use the
<buildtarget>extract</buildtarget> target. This target will only
retreive and extract the sources.
</para>
<note>
<para>
If you chose to run <buildtarget>extract</buildtarget> and then
decide afterwards that you do want to use the patches,
the best way forward is to ?
</para>
</note>
<note>
<para>
New port note:
You will need to generate a minimum port structure and Makefile that downloads the sources before you can execute these steps.
</para>
</note>
</step>
<step>
<screen>
&prompt.user; <userinput>cd port-dir</userinput>
&prompt.user; <userinput>make patch</userinput>
&prompt.user; <userinput>cd work/src-dir</userinput>
</screen>
<para>
Prior to making changes to the sources files, manually copy the files and add an *.orig extension.
This preserves the original file and allows the system to <command>diff</command> your changes and produce a new port patch.
</para>
<screen>
&prompt.user; <userinput>cp file.ext file.ext.orig</userinput>
</screen>
<para>
*Authors note. I had this work successfully without having done that. I built the patch, made my changes, then ran make makepatch and it worked?
</para>
<para>
Again, Repeat the above steps for each file at any location within <varname>WRKSRC</varname>
that needs a patch file created.
</para>
</step>
<step>
<para>
Once your changes are complete, return to the main port directory:
</para>
<screen>
&prompt.user; <userinput>cd port-dir</userinput>
</screen>
</step>
<step>
<para>
*** make checksum, portlink, ?
</para>
</step>
<step>
<para>
Finally, run the <buildtarget>makepatch</buildtarget> target.
</para>
<screen>
&prompt.user; <userinput>make makepatch</userinput>
</screen>
<para>
The makepatch target recursively searches <varname>WRKSRC</varname> for <filename>file</filename>/<filename>file.orig</filename>
pairs within <varname>WRKSRC</varname>, and creates a patch file in <varname>PATCHDIR</varname> from each pair
(using diff).
</para>
<note>
<para>
Any pre-existing patches in <varname>PATCHDIR</varname> that are *not* regenerated
during the above process are placed in a backup location in WRKDIR. This
backup location is deleted on <buildtarget>clean</buildtarget>. This may occur when not
using <buildtarget>patch</buildtarget> 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 <varname>PATCHDIR</varname> to ensure they have been created as expected.
</para>
</note>
<note>
<para>
+ Patch files are stored in <varname>PATCHDIR</varname>, by default <filename>files</filename> in the port
directory, which are automatically applied in the <buildtarget>patch</buildtarget> stage
</para>
</note>
</step>
</procedure>
</sect2>
</sect1>
<sect1 xml:id="ph-submitting">
<title>Submitting a patch</title>
<para>
The FreeBSD phabrictor review board is the place to submit patches. To submit a patch, create an account and log in. Navigate to Applications -> Code Review. Click the Create Diff file and submit the file generate by makepatch. At this point, others will review and comment on your work. If you are persistent, your patch will be accepted. Make no mistake, changes and difficulty are a normal part of the process of develop/test/report/develop. The people commenting on your work *want* you to be successful and are using their time to help you. If you accept their help and be persistent, you can become a better developer and FreeBSD gains another active port maintainer.
</para>
</sect1>
</chapter>