Attachment #32294 for bug #53425

View | Details | Raw Unified | Return to bug 53425
Collapse All | Expand All





      <para>In FreeBSD, anyone may submit a new port, or volunteer
	to maintain an existing port if it is unmaintained&mdash;you
	do not need any special commit privileges to do so.</para>
	Over time, if you gain experience and respect within the
	developer community, you may eventually gain a ports
	"commit bit" and thus become a ports "committer"
	&mdash;someone who has the right to commit to the FreeBSD
	ports CVS tree.</para>

      <para>A typical problem, however, is that there are many
	more people who want to add new ports than to maintain
	existing ports, and many more people who want to maintain
	existing ports than who want to serve as ports committers.
	Please keep this in mind when deciding whether to port
	something in the first place&mdash;it does not make the project
	overall look good to have ports in the tree that do not
	work because they are no longer maintained.</para>
    </chapter>

    <chapter id="own-port">

	(This is the file that actually
	controls the actual port build process, so if this document says
	one thing and <filename>bsd.port.mk</filename> says another,
	it's a bug in this document; please submit a PR.)
	Even if you do not hack <filename>Makefiles</filename>
	daily, it is well commented, and you will still gain much
	knowledge from it.  Additionally, you may send specific questions

          <filename>pkg-descr</filename> and
          <filename>pkg-plist</filename>.  Their
          <filename>pkg-</filename> prefix distinguishes them from
          other files.</para>
          <filename>pkg-comment</filename> files have now been folded
          into the <filename>Makefile</filename>s themselves as the
          one-line <literal>COMMENT</literal> variable and are
          thus deprecated.  Please make sure your port does not
          include them.)</para>

        <sect2>
          <title><filename>pkg-descr</filename></title>

          distfile
          we can <quote>house</quote> it ourselves
          on <hostid>ftp.FreeBSD.org</hostid>; however, this is the
          least-preferred solution.
          The distfile must be placed into
          <filename>~/public_distfiles/</filename> of someone's
          <hostid>freefall</hostid> account.

        <para>If your port's distfile changes all the time without any
          kind of version update by the author,
          consider putting the distfile in your home page and listing it as
          the first <makevar>MASTER_SITES</makevar>.  (If you can, try to
          talk the author out of doing this, because it really helps to
          establish some kind of source code control for projects like ours).
          Hosting your own version will
          prevent users
          from getting <errorname>checksum mismatch</errorname> errors, and
          also reduce the workload of maintainers of our FTP site.  Also, if

        and sections in that template to make your port easier for others to
        read.</para>

      <important>
	<para>There are a large number of port <literal>Makefile</literal>s
        in the ports collection that get the ordering of these variables
        wrong.  Please do not blindly copy other <literal>Makefile</literal>s
        from other ports without checking the order of these variables;
        this just encourages wider propogation of bad usage in the source
        base.  If in doubt of what the <quote>canonical order</quote> of the
        variables ought to be, try to follow the order in
        <filename>bsd.port.mk</filename>.  (In fact blindly copying
        other <literal>Makefile</literal>s may encourage even worse
        brokenness that just the ordering of the variables!)</para>
      </important>

      <para>Now, consider the following problems in sequence as you design
        your new <filename>Makefile</filename>:</para>


	    suffix <literal>,0</literal> on the earlier package.</para>

	  <para>Dropping or resetting <makevar>PORTEPOCH</makevar>
	    incorrectly leads
	    to no end of grief; if you do not understand the above discussion,
	    please keep after it until you do, or ask questions on
	    the mailing lists.</para>

              <literal>3</literal> is still numerically less than
              <literal>10</literal>.  This is the whole point of
              <makevar>PORTEPOCH</makevar> in the first place.</para>

            <para>Yes, this is subtle, but again, do not fiddle with
              the setting of <makevar>PORTEPOCH</makevar> until you
              understand this!</para>
	  </note>
        </sect3>
      </sect2>

        <para>This is a one-line description of the port.
          <emphasis>Please</emphasis> do not include the package name (or
          version number of the software) in the comment.  The comment
          should begin with a capital, and end without a period.  Here
          should not be surrounded by quotes.  Here
          is an example:</para>

        <programlisting>COMMENT=       A cat chasing a mouse all over the screen</programlisting>

          circular dependencies.  If you introduce one, you will have
          someone, somewhere in the world, whose FreeBSD installation will
          break almost immediately, with many others quickly to follow.
          These can really be hard to detect; if in doubt, before
          for instance, the GNOME libraries.  If in doubt, before
          you make that change, make sure you have done the following:
          <command>cd /usr/ports; make index</command>.  That process
          can be quite slow on older machines, but you may be able to

          existing implementation of what you are trying to do.  While
          hard to read, there are a great many seemingly-hard problems for
          which <filename>bsd.port.mk</filename> already provides a
          shorthand solution.</para>
          <filename>bsd.port.mk</filename> which was included by
          accident and is not continually being worked on.</para>
      </sect1>

      <sect1 id="dads-cc">

Return to bug 53425

Lines 53-73 Link Here

(-)book.sgml (-52 / +12 lines)
53		53
54	<para>In FreeBSD, anyone may submit a new port, or volunteer	54	<para>In FreeBSD, anyone may submit a new port, or volunteer
55	to maintain an existing port if it is unmaintained—you	55	to maintain an existing port if it is unmaintained—you
56	do not need any special commit privileges to do so.	56	do not need any special commit privileges to do so.</para>
57	Over time, if you gain experience and respect within the
58	developer community, you may eventually gain a ports
59	"commit bit" and thus become a ports "committer"
60	—someone who has the right to commit to the FreeBSD
61	ports CVS tree.</para>
62
63	<para>A typical problem, however, is that there are many
64	more people who want to add new ports than to maintain
65	existing ports, and many more people who want to maintain
66	existing ports than who want to serve as ports committers.
67	Please keep this in mind when deciding whether to port
68	something in the first place—it does not make the project
69	overall look good to have ports in the tree that do not
70	work because they are no longer maintained.</para>
71	</chapter>	57	</chapter>
72		58
73	<chapter id="own-port">	59	<chapter id="own-port">
Lines 86-92 Link Here
86	(This is the file that actually	72	(This is the file that actually
87	controls the actual port build process, so if this document says	73	controls the actual port build process, so if this document says
88	one thing and <filename>bsd.port.mk</filename> says another,	74	one thing and <filename>bsd.port.mk</filename> says another,
89	<filename>bsd.port.mk</filename> is correct.)	75	it's a bug in this document; please submit a PR.)
90	Even if you do not hack <filename>Makefiles</filename>	76	Even if you do not hack <filename>Makefiles</filename>
91	daily, it is well commented, and you will still gain much	77	daily, it is well commented, and you will still gain much
92	knowledge from it. Additionally, you may send specific questions	78	knowledge from it. Additionally, you may send specific questions
Lines 168-179 Link Here
168	<filename>pkg-descr</filename> and	154	<filename>pkg-descr</filename> and
169	<filename>pkg-plist</filename>. Their	155	<filename>pkg-plist</filename>. Their
170	<filename>pkg-</filename> prefix distinguishes them from	156	<filename>pkg-</filename> prefix distinguishes them from
171	other files. (Note: the former	157	other files.</para>
172	<filename>pkg-comment</filename> files have now been folded
173	into the <filename>Makefile</filename>s themselves as the
174	one-line <literal>COMMENT</literal> variable and are
175	thus deprecated. Please make sure your port does not
176	include them.)</para>
177		158
178	<sect2>	159	<sect2>
179	<title><filename>pkg-descr</filename></title>	160	<title><filename>pkg-descr</filename></title>
Lines 574-580 Link Here
574	distfile	555	distfile
575	we can <quote>house</quote> it ourselves	556	we can <quote>house</quote> it ourselves
576	on <hostid>ftp.FreeBSD.org</hostid>; however, this is the	557	on <hostid>ftp.FreeBSD.org</hostid>; however, this is the
577	least-preferred solution, as files housed there tend to get stale.	558	least-preferred solution.
578	The distfile must be placed into	559	The distfile must be placed into
579	<filename>~/public_distfiles/</filename> of someone's	560	<filename>~/public_distfiles/</filename> of someone's
580	<hostid>freefall</hostid> account.	561	<hostid>freefall</hostid> account.
Lines 587-596 Link Here
587	<para>If your port's distfile changes all the time without any	568	<para>If your port's distfile changes all the time without any
588	kind of version update by the author,	569	kind of version update by the author,
589	consider putting the distfile in your home page and listing it as	570	consider putting the distfile in your home page and listing it as
590	the first <makevar>MASTER_SITES</makevar>. (It is too bad we	571	the first <makevar>MASTER_SITES</makevar>. (If you can, try to
591	cannot always talk port authors out of doing this, because it	572	talk the author out of doing this, because it really helps to
592	really helps to establish some kind of source code control, but	573	establish some kind of source code control for projects like ours).
593	alas this is not always easy). Hosting your own version will	574	Hosting your own version will
594	prevent users	575	prevent users
595	from getting <errorname>checksum mismatch</errorname> errors, and	576	from getting <errorname>checksum mismatch</errorname> errors, and
596	also reduce the workload of maintainers of our FTP site. Also, if	577	also reduce the workload of maintainers of our FTP site. Also, if
Lines 725-743 Link Here
725	and sections in that template to make your port easier for others to	706	and sections in that template to make your port easier for others to
726	read.</para>	707	read.</para>
727		708
728	<important>
729	<para>There are a large number of port <literal>Makefile</literal>s
730	in the ports collection that get the ordering of these variables
731	wrong. Please do not blindly copy other <literal>Makefile</literal>s
732	from other ports without checking the order of these variables;
733	this just encourages wider propogation of bad usage in the source
734	base. If in doubt of what the <quote>canonical order</quote> of the
735	variables ought to be, try to follow the order in
736	<filename>bsd.port.mk</filename>. (In fact blindly copying
737	other <literal>Makefile</literal>s may encourage even worse
738	brokenness that just the ordering of the variables!)</para>
739	</important>
740
741	<para>Now, consider the following problems in sequence as you design	709	<para>Now, consider the following problems in sequence as you design
742	your new <filename>Makefile</filename>:</para>	710	your new <filename>Makefile</filename>:</para>
743		711
Lines 912-918 Link Here
912	suffix <literal>,0</literal> on the earlier package.</para>	880	suffix <literal>,0</literal> on the earlier package.</para>
913		881
914	<para>Dropping or resetting <makevar>PORTEPOCH</makevar>	882	<para>Dropping or resetting <makevar>PORTEPOCH</makevar>
915	incorrectly is a common error in the ports collection and leads	883	incorrectly leads
916	to no end of grief; if you do not understand the above discussion,	884	to no end of grief; if you do not understand the above discussion,
917	please keep after it until you do, or ask questions on	885	please keep after it until you do, or ask questions on
918	the mailing lists.</para>	886	the mailing lists.</para>
Lines 1001-1010 Link Here
1001	<literal>3</literal> is still numerically less than	969	<literal>3</literal> is still numerically less than
1002	<literal>10</literal>. This is the whole point of	970	<literal>10</literal>. This is the whole point of
1003	<makevar>PORTEPOCH</makevar> in the first place.</para>	971	<makevar>PORTEPOCH</makevar> in the first place.</para>
1004
1005	<para>Yes, this is subtle, but again, do not fiddle with
1006	the setting of <makevar>PORTEPOCH</makevar> until you
1007	understand this!</para>
1008	</note>	972	</note>
1009	</sect3>	973	</sect3>
1010	</sect2>	974	</sect2>
Lines 2749-2756 Link Here
2749	<para>This is a one-line description of the port.	2713	<para>This is a one-line description of the port.
2750	<emphasis>Please</emphasis> do not include the package name (or	2714	<emphasis>Please</emphasis> do not include the package name (or
2751	version number of the software) in the comment. The comment	2715	version number of the software) in the comment. The comment
2752	should begin with a capital, end without a period, and	2716	should begin with a capital, and end without a period. Here
2753	should not be surrounded by quotes. Here
2754	is an example:</para>	2717	is an example:</para>
2755		2718
2756	<programlisting>COMMENT= A cat chasing a mouse all over the screen</programlisting>	2719	<programlisting>COMMENT= A cat chasing a mouse all over the screen</programlisting>
Lines 3114-3121 Link Here
3114	circular dependencies. If you introduce one, you will have	3077	circular dependencies. If you introduce one, you will have
3115	someone, somewhere in the world, whose FreeBSD installation will	3078	someone, somewhere in the world, whose FreeBSD installation will
3116	break almost immediately, with many others quickly to follow.	3079	break almost immediately, with many others quickly to follow.
3117	These can really be hard to detect, especially with,	3080	These can really be hard to detect; if in doubt, before
3118	for instance, the GNOME libraries. If in doubt, before
3119	you make that change, make sure you have done the following:	3081	you make that change, make sure you have done the following:
3120	<command>cd /usr/ports; make index</command>. That process	3082	<command>cd /usr/ports; make index</command>. That process
3121	can be quite slow on older machines, but you may be able to	3083	can be quite slow on older machines, but you may be able to
Lines 6202-6210 Link Here
6202	existing implementation of what you are trying to do. While	6164	existing implementation of what you are trying to do. While
6203	hard to read, there are a great many seemingly-hard problems for	6165	hard to read, there are a great many seemingly-hard problems for
6204	which <filename>bsd.port.mk</filename> already provides a	6166	which <filename>bsd.port.mk</filename> already provides a
6205	shorthand solution. There is almost nothing in	6167	shorthand solution.</para>
6206	<filename>bsd.port.mk</filename> which was included by
6207	accident and is not continually being worked on.</para>
6208	</sect1>	6168	</sect1>
6209		6169
6210	<sect1 id="dads-cc">	6170	<sect1 id="dads-cc">