Attachment #39047 for bug #61653

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




    <chapter id="own-port">
      <title>Making a port yourself</title>

      <para>So, you are interested in making your own port or
	upgrading an existing one?  Great!</para>

      <para>What follows are some guidelines for creating a new port for

	  Also add a short description of the program you ported
	  to the <quote>Description</quote> field of the PR and
	  the shar or uuencoded tarfile to the
	  <quote>Fix</quote> field.</para>

	<note>
	  <para>You can make our work a lot easier, if you use a good
	    description in the synopsis of the problem report.
	    We prefer something like
	    <quote>New port: &lt;category&gt;/&lt;portname&gt;
	    &lt;short description of the port&gt;</quote> for new ports and
	    <quote>Update port: &lt;category&gt;/&lt;portname&gt;
	    &lt;short description of the update&gt;</quote> for port updates.
	    If you stick to this scheme, the chance that someone takes a
	    look at your PR soon is much bigger.</para>
	</note>

	<para>One more time, <emphasis>do not include the original source
	    distfile, the <filename>work</filename> directory, or the package

	  <ulink url="../../articles/contributors/contrib-additional.html">Additional FreeBSD Contributors</ulink>
	  and other files. Isn't that great?!? <!-- smiley
	  -->:-)</para>

	<note>
	  <para>You can make our work a lot easier, if you use a good
	    description in the synopsis of the problem report.
	    We prefer something like
	    <quote>New port: &lt;short description of the port&gt;</quote> for
	    new ports and
	    <quote>Update port: &lt;category&gt;/&lt;port&gt; &lt;short description
	    of the update&gt;</quote> for port updates.
	    If you stick to this scheme, the chance that one takes a look at
	    your PR soon is much bigger.</para>
	</note>
      </sect1>
    </chapter>


	    every increase of <makevar>PORTVERSION</makevar> (i.e.
	    every time a new official vendor release is made), and
	    appended to the package name if non-zero.
	    Changes to <makevar>PORTREVISION</makevar> are
	    used by automated tools (e.g.  &man.pkg.version.1;)
	    to highlight the fact that a new package is
	    available.</para>

	  <para><makevar>PORTREVISION</makevar> should be increased
	    each time a change is made to the port which significantly
	    affects the content or structure of the derived
	    package.</para>


	    <listitem>
	      <para>Addition of patches to correct security
		vulnerabilities, bugs, or to add new functionality to
		the port.</para>
	    </listitem>

	    <listitem>

		the changes do not introduce any functional change on
		any other platforms on which the port did previously
		build). Since <makevar>PORTREVISION</makevar> reflects
		the content of the package, if the package was not
		previously buildable then there is no need to increase
		<makevar>PORTREVISION</makevar> to mark a
		change.</para>

	    actually work at all), and weigh that against that fact
	    that it will cause everyone who regularly updates their
	    ports tree to be compelled to update. If yes, the
	    <makevar>PORTREVISION</makevar> should be bumped.</para>
	    automated tools (e.g.  &man.pkg.version.1;)
	    will highlight the fact that a new package is
	    available.</para>
	</sect3>

	<sect3>

		  safely delete <literal>misc</literal> and just put the port
		  in that other subdirectory!  If at all possible, try to
		  find a better category for your port than
		  <literal>misc</literal>, as ports tend to get overlooked
		  in here.</entry>
	      </row>


		  If your port <emphasis>is</emphasis> an X
		  application, define <makevar>USE_XLIB</makevar> (implied by
		  <makevar>USE_IMAKE</makevar>) and put it in the appropriate
		  category.</entry>
		  <filename>x11-*</filename> categories (see below).</entry>
	      </row>

	      <row>

	<para><makevar>DISTNAME</makevar> is the name of the port as
	  called by the authors of the software.
	  <makevar>DISTNAME</makevar> defaults to
	  <literal>${PORTNAME}-${PORTVERSION}</literal>, so override it only if necessary.
	  <makevar>DISTNAME</makevar> is only used in two places.
	  First, the distribution file list
	  (<makevar>DISTFILES</makevar>) defaults to

	<note>
	  <para><makevar>PKGNAMEPREFIX</makevar> and
	    <makevar>PKGNAMESUFFIX</makevar> do not affect
	    <makevar>DISTNAME</makevar>.  Also note that if
	    <makevar>WRKSRC</makevar> is equal to
	    <filename>work/<makevar>${PORTNAME}-${PORTVERSION}</makevar></filename>
	    while the original source archive is named something other than


	<para>These variables are defined in
	  <filename>/usr/ports/Mk/bsd.sites.mk</filename>.  There are
	  new entries added all the time, so make sure to check the
	  latest version of this file before submitting a port.</para>

	<para>The user can also set the <makevar>MASTER_SITE_*</makevar>

	<para>Set your mail-address here.  Please.  <!-- smiley
	  --><emphasis>:-)</emphasis></para>

	<para>Note that only a single address without comment part is
	  allowed as a <makevar>MAINTAINER</makevar> value.
	  The format used should be <literal>user@hostname.domain</literal>.
	  Please do not include any descriptive text such as your real
	  name in this entry&mdash;that merely confuses
	  <filename>bsd.port.mk</filename>.  Instead, put that information

	  refer to the <ulink url="../developers-handbook/policies.html#POLICIES-MAINTAINER">MAINTAINER on
	    Makefiles</ulink> section.</para>

	<para>Note that only a single address without comment part is
	  allowed as a <makevar>MAINTAINER</makevar> value.</para>

	<para>If the maintainer of a port does not respond to an update
	  request from a user after two weeks (excluding major public
	  holidays), then that is considered a maintainer timeout, and the

	  package is not generally useful, and the application should always
	  be compiled from the source code.  For example, if the application
	  has configuration information that is site specific hard coded in to
	  it at compile time, set <makevar>NO_PACKAGE</makevar>.</para>

	<para><makevar>NO_PACKAGE</makevar> should be set to a string
	  describing the reason why the package should not be

	  occurrences of <filename>/usr/local</filename> (or
	  <filename>/usr/X11R6</filename> for X ports that do not use imake)
	  in the various <filename>scripts/Makefile</filename>s in the port to read
	  <makevar>${PREFIX}</makevar>, as this variable is automatically passed
	  down to every stage of the build and install processes.</para>

	<para>Make sure your application is not installing things in

	<screen>&prompt.root; <userinput>make clean; make package PREFIX=/var/tmp/<replaceable>port-name</replaceable></userinput></screen>

	<para>If anything is installed outside of <makevar>PREFIX</makevar>,
	the package creation process will complain that it
	cannot find the files.</para>

	<!-- XXX This paragraph is confusing and poorly indented. -->


      <para>If the maintainer asks you to do the upgrade or the maintainer
	is <literal>ports@FreeBSD.org</literal>,
	please make the upgrade and save the result of the
	recursive <command>diff</command> output
	of the new and old
	ports directories.  (e.g., if your modified port directory is
	called <filename>superedit</filename> and the original is in our tree
	as <filename>superedit.bak</filename>, then save the result of
	<command>diff -ruN superedit.bak superedit</command>).  Either
	unified or context diff is fine, but port committers generally
	prefer unified diffs.  Note the use of the <literal>-N</literal>
	option&mdash;this is the accepted way to force diff to properly
	deal with the case of new files being added or old files being
	deleted.  Before sendingus the diff, please examine the
	output to make sure all the changes make sense.</para>

      <para> The best way to
	the output to make sure all the changes make sense.  The best way to
	send us the diff is by including it via &man.send-pr.1; (category
	<literal>ports</literal>).  If you are going to be the maintainer for the port,
	be sure to put <literal>[maintainer update]</literal> at the beginning
	of your synopsis line and/or set the <quote>Class</quote> of your PR
	to <literal>maintainer-update</literal>.  Please mention any added or

      </important>

      <note>
	<para>Once again, please use &man.diff.1;, and not &man.shar.1;, to send
	updates to existing ports!</para>
      </note>
    </chapter>


	      number of vulnerable FreeBSD hosts (we like being known
	      for being secure), however sometimes there is a
	      noticeable time gap between disclosure of a
	      vulnerability and an updated release of the
	      vulnerable software.  Do not mark a port
	      <makevar>FORBIDDEN</makevar> for any reason other than
	      security.</para>
	  </listitem>

Return to bug 61653

Lines 64-70 Link Here

(-)book.sgml (-47 / +46 lines)
64	<chapter id="own-port">	64	<chapter id="own-port">
65	<title>Making a port yourself</title>	65	<title>Making a port yourself</title>
66		66
67	<para>So, you are still interested in making your own port or	67	<para>So, you are interested in making your own port or
68	upgrading an existing one? Great!</para>	68	upgrading an existing one? Great!</para>
69		69
70	<para>What follows are some guidelines for creating a new port for	70	<para>What follows are some guidelines for creating a new port for
Lines 348-355 Link Here
348	Also add a short description of the program you ported	348	Also add a short description of the program you ported
349	to the <quote>Description</quote> field of the PR and	349	to the <quote>Description</quote> field of the PR and
350	the shar or uuencoded tarfile to the	350	the shar or uuencoded tarfile to the
351	<quote>Fix</quote> field. The latter one helps the committers	351	<quote>Fix</quote> field.</para>
352	a lot, who use scripts for the ports-work.</para>	352
		353	<note>
		354	<para>You can make our work a lot easier, if you use a good
		355	description in the synopsis of the problem report.
		356	We prefer something like
		357	<quote>New port: <category>/<portname>
		358	<short description of the port></quote> for new ports and
		359	<quote>Update port: <category>/<portname>
		360	<short description of the update></quote> for port updates.
		361	If you stick to this scheme, the chance that someone takes a
		362	look at your PR soon is much bigger.</para>
		363	</note>
353		364
354	<para>One more time, <emphasis>do not include the original source	365	<para>One more time, <emphasis>do not include the original source
355	distfile, the <filename>work</filename> directory, or the package	366	distfile, the <filename>work</filename> directory, or the package
Lines 375-392 Link Here
375	<ulink url="../../articles/contributors/contrib-additional.html">Additional FreeBSD Contributors</ulink>	386	<ulink url="../../articles/contributors/contrib-additional.html">Additional FreeBSD Contributors</ulink>
376	and other files. Isn't that great?!? <!-- smiley	387	and other files. Isn't that great?!? <!-- smiley
377	-->:-)</para>	388	-->:-)</para>
378
379	<note>
380	<para>You can make our work a lot easier, if you use a good
381	description in the synopsis of the problem report.
382	We prefer something like
383	<quote>New port: <short description of the port></quote> for
384	new ports and
385	<quote>Update port: <category>/<port> <short description
386	of the update></quote> for port updates.
387	If you stick to this scheme, the chance that one takes a look at
388	your PR soon is much bigger.</para>
389	</note>
390	</sect1>	389	</sect1>
391	</chapter>	390	</chapter>
392		391
Lines 757-764 Link Here
757	every increase of <makevar>PORTVERSION</makevar> (i.e.	756	every increase of <makevar>PORTVERSION</makevar> (i.e.
758	every time a new official vendor release is made), and	757	every time a new official vendor release is made), and
759	appended to the package name if non-zero.	758	appended to the package name if non-zero.
760	<makevar>PORTREVISION</makevar> is increased each time a	759	Changes to <makevar>PORTREVISION</makevar> are
761	change is made to the FreeBSD port which significantly	760	used by automated tools (e.g. &man.pkg.version.1;)
		761	to highlight the fact that a new package is
		762	available.</para>
		763
		764	<para><makevar>PORTREVISION</makevar> should be increased
		765	each time a change is made to the port which significantly
762	affects the content or structure of the derived	766	affects the content or structure of the derived
763	package.</para>	767	package.</para>
764		768
Lines 769-775 Link Here
769	<listitem>	773	<listitem>
770	<para>Addition of patches to correct security	774	<para>Addition of patches to correct security
771	vulnerabilities, bugs, or to add new functionality to	775	vulnerabilities, bugs, or to add new functionality to
772	the FreeBSD port.</para>	776	the port.</para>
773	</listitem>	777	</listitem>
774		778
775	<listitem>	779	<listitem>
Lines 832-838 Link Here
832	the changes do not introduce any functional change on	836	the changes do not introduce any functional change on
833	any other platforms on which the port did previously	837	any other platforms on which the port did previously
834	build). Since <makevar>PORTREVISION</makevar> reflects	838	build). Since <makevar>PORTREVISION</makevar> reflects
835	the content of the package, if no package was	839	the content of the package, if the package was not
836	previously buildable then there is no need to increase	840	previously buildable then there is no need to increase
837	<makevar>PORTREVISION</makevar> to mark a	841	<makevar>PORTREVISION</makevar> to mark a
838	change.</para>	842	change.</para>
Lines 846-855 Link Here
846	actually work at all), and weigh that against that fact	850	actually work at all), and weigh that against that fact
847	that it will cause everyone who regularly updates their	851	that it will cause everyone who regularly updates their
848	ports tree to be compelled to update. If yes, the	852	ports tree to be compelled to update. If yes, the
849	<makevar>PORTREVISION</makevar> should be bumped so that	853	<makevar>PORTREVISION</makevar> should be bumped.</para>
850	automated tools (e.g. &man.pkg.version.1;)
851	will highlight the fact that a new package is
852	available.</para>
853	</sect3>	854	</sect3>
854		855
855	<sect3>	856	<sect3>
Lines 1577-1583 Link Here
1577	safely delete <literal>misc</literal> and just put the port	1578	safely delete <literal>misc</literal> and just put the port
1578	in that other subdirectory! If at all possible, try to	1579	in that other subdirectory! If at all possible, try to
1579	find a better category for your port than	1580	find a better category for your port than
1580	<literal>misc</literal> ports tend to get overlooked	1581	<literal>misc</literal>, as ports tend to get overlooked
1581	in here.</entry>	1582	in here.</entry>
1582	</row>	1583	</row>
1583		1584
Lines 1814-1821 Link Here
1814	If your port <emphasis>is</emphasis> an X	1815	If your port <emphasis>is</emphasis> an X
1815	application, define <makevar>USE_XLIB</makevar> (implied by	1816	application, define <makevar>USE_XLIB</makevar> (implied by
1816	<makevar>USE_IMAKE</makevar>) and put it in the appropriate	1817	<makevar>USE_IMAKE</makevar>) and put it in the appropriate
1817	categories. Also, many of them go into other	1818	category.</entry>
1818	<filename>x11-*</filename> categories (see below).</entry>
1819	</row>	1819	</row>
1820		1820
1821	<row>	1821	<row>
Lines 1938-1944 Link Here
1938	<para><makevar>DISTNAME</makevar> is the name of the port as	1938	<para><makevar>DISTNAME</makevar> is the name of the port as
1939	called by the authors of the software.	1939	called by the authors of the software.
1940	<makevar>DISTNAME</makevar> defaults to	1940	<makevar>DISTNAME</makevar> defaults to
1941	<literal>${PORTNAME}-${PORTVERSION}</literal>, so override it if necessary.	1941	<literal>${PORTNAME}-${PORTVERSION}</literal>, so override it only if necessary.
1942	<makevar>DISTNAME</makevar> is only used in two places.	1942	<makevar>DISTNAME</makevar> is only used in two places.
1943	First, the distribution file list	1943	First, the distribution file list
1944	(<makevar>DISTFILES</makevar>) defaults to	1944	(<makevar>DISTFILES</makevar>) defaults to
Lines 1950-1956 Link Here
1950	<note>	1950	<note>
1951	<para><makevar>PKGNAMEPREFIX</makevar> and	1951	<para><makevar>PKGNAMEPREFIX</makevar> and
1952	<makevar>PKGNAMESUFFIX</makevar> do not affect	1952	<makevar>PKGNAMESUFFIX</makevar> do not affect
1953	<makevar>DISTNAME</makevar>. Also note that when	1953	<makevar>DISTNAME</makevar>. Also note that if
1954	<makevar>WRKSRC</makevar> is equal to	1954	<makevar>WRKSRC</makevar> is equal to
1955	<filename>work/<makevar>${PORTNAME}-${PORTVERSION}</makevar></filename>	1955	<filename>work/<makevar>${PORTNAME}-${PORTVERSION}</makevar></filename>
1956	while the original source archive is named something other than	1956	while the original source archive is named something other than
Lines 1997-2003 Link Here
1997		1997
1998	<para>These variables are defined in	1998	<para>These variables are defined in
1999	<filename>/usr/ports/Mk/bsd.sites.mk</filename>. There are	1999	<filename>/usr/ports/Mk/bsd.sites.mk</filename>. There are
2000	new archives added all the time, so make sure to check the	2000	new entries added all the time, so make sure to check the
2001	latest version of this file before submitting a port.</para>	2001	latest version of this file before submitting a port.</para>
2002		2002
2003	<para>The user can also set the <makevar>MASTER_SITE_*</makevar>	2003	<para>The user can also set the <makevar>MASTER_SITE_*</makevar>
Lines 2793-2799 Link Here
2793	<para>Set your mail-address here. Please. <!-- smiley	2793	<para>Set your mail-address here. Please. <!-- smiley
2794	--><emphasis>:-)</emphasis></para>	2794	--><emphasis>:-)</emphasis></para>
2795		2795
2796	<para>The format used should be <literal>user@hostname.domain</literal>.	2796	<para>Note that only a single address without comment part is
		2797	allowed as a <makevar>MAINTAINER</makevar> value.
		2798	The format used should be <literal>user@hostname.domain</literal>.
2797	Please do not include any descriptive text such as your real	2799	Please do not include any descriptive text such as your real
2798	name in this entry—that merely confuses	2800	name in this entry—that merely confuses
2799	<filename>bsd.port.mk</filename>. Instead, put that information	2801	<filename>bsd.port.mk</filename>. Instead, put that information
Lines 2803-2811 Link Here
2803	refer to the <ulink url="../developers-handbook/policies.html#POLICIES-MAINTAINER">MAINTAINER on	2805	refer to the <ulink url="../developers-handbook/policies.html#POLICIES-MAINTAINER">MAINTAINER on
2804	Makefiles</ulink> section.</para>	2806	Makefiles</ulink> section.</para>
2805		2807
2806	<para>Note that only a single address without comment part is
2807	allowed as a <makevar>MAINTAINER</makevar> value.</para>
2808
2809	<para>If the maintainer of a port does not respond to an update	2808	<para>If the maintainer of a port does not respond to an update
2810	request from a user after two weeks (excluding major public	2809	request from a user after two weeks (excluding major public
2811	holidays), then that is considered a maintainer timeout, and the	2810	holidays), then that is considered a maintainer timeout, and the
Lines 3440-3446 Link Here
3440	package is not generally useful, and the application should always	3443	package is not generally useful, and the application should always
3441	be compiled from the source code. For example, if the application	3444	be compiled from the source code. For example, if the application
3442	has configuration information that is site specific hard coded in to	3445	has configuration information that is site specific hard coded in to
3443	it at compile time.</para>	3446	it at compile time, set <makevar>NO_PACKAGE</makevar>.</para>
3444		3447
3445	<para><makevar>NO_PACKAGE</makevar> should be set to a string	3448	<para><makevar>NO_PACKAGE</makevar> should be set to a string
3446	describing the reason why the package should not be	3449	describing the reason why the package should not be
Lines 4547-4553 Link Here
4547	occurrences of <filename>/usr/local</filename> (or	4549	occurrences of <filename>/usr/local</filename> (or
4548	<filename>/usr/X11R6</filename> for X ports that do not use imake)	4550	<filename>/usr/X11R6</filename> for X ports that do not use imake)
4549	in the various <filename>scripts/Makefile</filename>s in the port to read	4551	in the various <filename>scripts/Makefile</filename>s in the port to read
4550	<makevar>PREFIX</makevar>, as this variable is automatically passed	4552	<makevar>${PREFIX}</makevar>, as this variable is automatically passed
4551	down to every stage of the build and install processes.</para>	4553	down to every stage of the build and install processes.</para>
4552		4554
4553	<para>Make sure your application is not installing things in	4555	<para>Make sure your application is not installing things in
Lines 4557-4563 Link Here
4557	<screen>&prompt.root; <userinput>make clean; make package PREFIX=/var/tmp/<replaceable>port-name</replaceable></userinput></screen>	4559	<screen>&prompt.root; <userinput>make clean; make package PREFIX=/var/tmp/<replaceable>port-name</replaceable></userinput></screen>
4558		4560
4559	<para>If anything is installed outside of <makevar>PREFIX</makevar>,	4561	<para>If anything is installed outside of <makevar>PREFIX</makevar>,
4560	making the package creation process will complain that it	4562	the package creation process will complain that it
4561	cannot find the files.</para>	4563	cannot find the files.</para>
4562		4564
4563	<!-- XXX This paragraph is confusing and poorly indented. -->	4565	<!-- XXX This paragraph is confusing and poorly indented. -->
Lines 4634-4656 Link Here
4634		4636
4635	<para>If the maintainer asks you to do the upgrade or the maintainer	4637	<para>If the maintainer asks you to do the upgrade or the maintainer
4636	is <literal>ports@FreeBSD.org</literal>,	4638	is <literal>ports@FreeBSD.org</literal>,
4637	please make the upgrade and send the	4639	please make the upgrade and save the result of the
4638	recursive <command>diff</command> output	4640	recursive <command>diff</command> output
4639	of the new and old	4641	of the new and old
4640	ports directories to us (e.g., if your modified port directory is	4642	ports directories. (e.g., if your modified port directory is
4641	called <filename>superedit</filename> and the original is in our tree	4643	called <filename>superedit</filename> and the original is in our tree
4642	as <filename>superedit.bak</filename>, then send us the result of	4644	as <filename>superedit.bak</filename>, then save the result of
4643	<command>diff -ruN superedit.bak superedit</command>). Either	4645	<command>diff -ruN superedit.bak superedit</command>). Either
4644	unified or context diff is fine, but port committers generally	4646	unified or context diff is fine, but port committers generally
4645	prefer unified diffs. Note the use of the <literal>-N</literal>	4647	prefer unified diffs. Note the use of the <literal>-N</literal>
4646	option—this is the accepted way to force diff to properly	4648	option—this is the accepted way to force diff to properly
4647	deal with the case of new files being added or old files being	4649	deal with the case of new files being added or old files being
4648	deleted.</para>	4650	deleted. Before sendingus the diff, please examine the
		4651	output to make sure all the changes make sense.</para>
4649		4652
4650	<para>Please examine	4653	<para> The best way to
4651	the output to make sure all the changes make sense. The best way to
4652	send us the diff is by including it via &man.send-pr.1; (category	4654	send us the diff is by including it via &man.send-pr.1; (category
4653	<literal>ports</literal>). If you are the maintainer for the port,	4655	<literal>ports</literal>). If you are going to be the maintainer for the port,
4654	be sure to put <literal>[maintainer update]</literal> at the beginning	4656	be sure to put <literal>[maintainer update]</literal> at the beginning
4655	of your synopsis line and/or set the <quote>Class</quote> of your PR	4657	of your synopsis line and/or set the <quote>Class</quote> of your PR
4656	to <literal>maintainer-update</literal>. Please mention any added or	4658	to <literal>maintainer-update</literal>. Please mention any added or
Lines 4676-4683 Link Here
4676	</important>	4678	</important>
4677		4679
4678	<note>	4680	<note>
4679	<para>Once again, please use &man.diff.1; and not &man.shar.1; to send	4681	<para>Once again, please use &man.diff.1;, and not &man.shar.1;, to send
4680	updates to existing ports!</para>	4682	updates to existing ports!</para>
4681	</note>	4683	</note>
4682	</chapter>	4684	</chapter>
4683		4685
Lines 6397-6404 Link Here
6397	number of vulnerable FreeBSD hosts (we like being known	6399	number of vulnerable FreeBSD hosts (we like being known
6398	for being secure), however sometimes there is a	6400	for being secure), however sometimes there is a
6399	noticeable time gap between disclosure of a	6401	noticeable time gap between disclosure of a
6400	vulnerability and an updated software release of a piece	6402	vulnerability and an updated release of the
6401	of vulnerable software. Do not mark a port	6403	vulnerable software. Do not mark a port
6402	<makevar>FORBIDDEN</makevar> for any reason other than	6404	<makevar>FORBIDDEN</makevar> for any reason other than
6403	security.</para>	6405	security.</para>
6404	</listitem>	6406	</listitem>