Add a detailed list of instructions on how to add a new category to the
ports collection. One step is not yet defined; hopefully this will be resolved soon. PR: docs/64144 Reviewed by: eik and many others Approved by: ceri (mentor)
This commit is contained in:
Mark Linimon
parent
13d8c0a686
commit
1d33692e8e
Notes:
svn2git
2020-12-08 03:00:23 +00:00
svn path=/head/; revision=20493
1 changed files with 170 additions and 3 deletions
|
|
@ -678,11 +678,11 @@ alias scvs env CVS_RSH=ssh cvs -d <replaceable>user</replaceable>@ncvs.freebsd.o
|
|||
</itemizedlist>
|
||||
|
||||
<para>You will almost certainly get a conflict because
|
||||
of the <literal>$Id: article.sgml,v 1.183 2004-04-02 19:30:29 des Exp $</literal> (or in FreeBSD's case,
|
||||
of the <literal>$Id: article.sgml,v 1.184 2004-04-04 17:05:14 linimon Exp $</literal> (or in FreeBSD's case,
|
||||
<literal>$<!-- stop expansion -->FreeBSD<!-- stop expansion -->$</literal>)
|
||||
lines, so you will have to edit the file to resolve the conflict
|
||||
(remove the marker lines and the second <literal>$Id: article.sgml,v 1.183 2004-04-02 19:30:29 des Exp $</literal> line,
|
||||
leaving the original <literal>$Id: article.sgml,v 1.183 2004-04-02 19:30:29 des Exp $</literal> line intact).</para>
|
||||
(remove the marker lines and the second <literal>$Id: article.sgml,v 1.184 2004-04-04 17:05:14 linimon Exp $</literal> line,
|
||||
leaving the original <literal>$Id: article.sgml,v 1.184 2004-04-04 17:05:14 linimon Exp $</literal> line intact).</para>
|
||||
</listitem>
|
||||
|
||||
<listitem>
|
||||
|
|
@ -2521,6 +2521,173 @@ docs:Documentation Bug:freebsd-doc:</programlisting>
|
|||
</qandaentry>
|
||||
</qandadiv>
|
||||
|
||||
<qandadiv>
|
||||
<title>Creating a New Category</title>
|
||||
|
||||
<qandaentry>
|
||||
<question>
|
||||
<para>What is the procedure for creating a new category?</para>
|
||||
</question>
|
||||
|
||||
<answer>
|
||||
<para>A developer who wishes to propose a new category
|
||||
should submit a detailed rationale for the new category,
|
||||
including why existing categories are not sufficient,
|
||||
and the list of ports proposed to move.</para>
|
||||
|
||||
<para>Before submitting, keep in mind that there is a fair
|
||||
amount of work involved from multiple parties; that the
|
||||
changes affect everyone who wants to keep up-to-date with
|
||||
the entire ports tree; and that such proposals tend to
|
||||
attract controversy.</para>
|
||||
</answer>
|
||||
</qandaentry>
|
||||
|
||||
<qandaentry>
|
||||
<question>
|
||||
<para>What do I need to do?</para>
|
||||
</question>
|
||||
|
||||
<answer>
|
||||
<para>The procedure is a strict superset of the one to
|
||||
repocopy individual ports (see above).</para>
|
||||
|
||||
<para>File a PR in <application>GNATS</application>, listing the
|
||||
reasons for the category request. Preferably, this should
|
||||
also include patches for <filename>Makefile</filename>s for
|
||||
the old ports, the <filename>Makefile</filename>s for their
|
||||
old categories, and the <makevar>VALID_CATEGORIES</makevar>
|
||||
definition in <filename>ports/Mk/bsd.port.mk</filename>.
|
||||
Assign the PR to the &a.portmgr; (as <literal>portmgr</literal>).
|
||||
If they approve it, it will be reassigned to &a.cvs; (as
|
||||
<literal>cvs</literal>), who will do a repository copy from
|
||||
the old to the new locations and reassign the PR back to you.
|
||||
Once everything is done, perform the following steps:</para>
|
||||
|
||||
<procedure>
|
||||
<step>
|
||||
<para>Upgrade each copied port's
|
||||
<filename>Makefile</filename>. Do not connect the
|
||||
new category to the build yet.</para>
|
||||
|
||||
<para>To do this, you will need to:
|
||||
<procedure>
|
||||
<step>
|
||||
<para>Change the port's <makevar>CATEGORIES</makevar>
|
||||
(this was the point of the exercise, remember?)
|
||||
The new category should be listed
|
||||
<emphasis>first</emphasis>. This will help to
|
||||
ensure that the the <makevar>PKGORIGIN</makevar>
|
||||
is correct.</para>
|
||||
</step>
|
||||
|
||||
<step>
|
||||
<para>Run a <command>make describe</command>. Since
|
||||
the top-level <command>make index</command> that
|
||||
you will be running in a few steps is an iteration
|
||||
of <command>make describe</command> over the entire
|
||||
ports hierarchy, catching any errors here will
|
||||
save you having to re-run that step later on.</para>
|
||||
</step>
|
||||
|
||||
<step>
|
||||
<para>If you want to be really thorough, now might
|
||||
be a good time to run &man.portlint.1;.</para>
|
||||
</step>
|
||||
</procedure>
|
||||
</step>
|
||||
|
||||
<step>
|
||||
<para>Check that the <makevar>PKGORIGIN</makevar>s are
|
||||
correct. The ports system uses each port's
|
||||
<makevar>CATEGORIES</makevar> entry to create
|
||||
its <makevar>PKGORIGIN</makevar>, which is used to
|
||||
connect installed packages to the port directory they
|
||||
were built from. If this entry is wrong, common port
|
||||
tools like &man.pkg.version.1; and
|
||||
&man.portupgrade.1; fail.</para>
|
||||
|
||||
<para>To do this, use the <filename>chkorigin.sh</filename>
|
||||
tool, as follows: <command>env
|
||||
PORTSDIR=<replaceable>/path/to/ports</replaceable>
|
||||
sh -e <replaceable>/path/to/ports</replaceable>/Tools/scripts/chkorigin.sh
|
||||
</command>. This will check <emphasis>every</emphasis>
|
||||
port in the ports tree, even those not connected to the
|
||||
build, so you can run it directly after the repocopy.
|
||||
Hint: do not forget to look at the
|
||||
<makevar>PKGORIGIN</makevar>s of any slave ports of the
|
||||
ports you just repocopied!</para>
|
||||
</step>
|
||||
|
||||
<step>
|
||||
<para>On your own local system, test the proposed
|
||||
changes: first, comment out the
|
||||
<makevar>SUBDIR</makevar> entries in the old
|
||||
ports' categories' <filename>Makefile</filename>s;
|
||||
then enable building the new category in
|
||||
<filename>ports/Makefile</filename>.
|
||||
Run <command>make checksubdirs</command> in the
|
||||
affected category directories to check the
|
||||
<makevar>SUBDIR</makevar> entries. Next, in
|
||||
the <filename class="directory">ports/</filename>
|
||||
directory, run <command>make index</command>. This
|
||||
can take over 40 minutes on even modern systems;
|
||||
however, it is a necessary step to prevent problems
|
||||
for other people.</para>
|
||||
</step>
|
||||
|
||||
<step>
|
||||
<para>Once this is done, you can commit the
|
||||
updated <filename>ports/Makefile</filename> to
|
||||
connect the new category to the build and also
|
||||
commit the <filename>Makefile</filename> changes
|
||||
for the old category or categories.</para>
|
||||
</step>
|
||||
|
||||
<step>
|
||||
<para>Change all the affected module entries in
|
||||
<filename>CVSROOT-ports/modules</filename>.</para>
|
||||
</step>
|
||||
|
||||
<step>
|
||||
<para>Add appropriate entries to
|
||||
<filename>ports/MOVED</filename>.</para>
|
||||
</step>
|
||||
|
||||
<step>
|
||||
<para>Update the instructions for &man.cvsup.1; by
|
||||
modifying <filename>distrib/cvsup/sup/README</filename>
|
||||
and adding the following files into
|
||||
<filename>cvsup/sup/ports-categoryname</filename>:
|
||||
<filename>list.cvs</filename> and
|
||||
<filename>releases</filename>. (Note: these are
|
||||
in the src, not the ports, repository).</para>
|
||||
</step>
|
||||
|
||||
<step>
|
||||
<para>Submit a docs PR to add the new category to both the
|
||||
<ulink url="../../books/porters-handbook/makefile-categories.html#PORTING-CATEGORIES">
|
||||
Porter's Handbook</ulink> and to
|
||||
<filename>www/en/ports/categories</filename>.</para>
|
||||
</step>
|
||||
|
||||
<step>
|
||||
<para>The procedure to update the <ulink
|
||||
url="../../../../ports/index.html">ports web pages</ulink>
|
||||
to reflect the new category is not yet defined.</para>
|
||||
</step>
|
||||
|
||||
<step>
|
||||
<para>Only once all the above have been done, and
|
||||
no one is any longer reporting problems with the
|
||||
new ports, should the old ports be deleted from
|
||||
their previous locations in the repository.</para>
|
||||
</step>
|
||||
</procedure>
|
||||
</answer>
|
||||
</qandaentry>
|
||||
</qandadiv>
|
||||
|
||||
<qandadiv>
|
||||
<title>Miscellaneous Questions</title>
|
||||
|
||||
|
|
|
|||
Loading…
Reference in a new issue