Attachment #32291 for bug #53422

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




  </bookinfo>


    <chapter id="why-port">
      <title>Introduction</title>

      <para>The FreeBSD ports collection is the way almost everyone
	installs applications ("ports") on FreeBSD.  Like everything
	else about FreeBSD, it is primarily a volunteer effort.
	It's important to keep this in mind when reading this
	document.</para>

      <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.
	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">
      <title>Making a port yourself</title>

      <para>So, you are still 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

        <para>Only a fraction of the variables
          (<makevar><replaceable>VAR</replaceable></makevar>) that can be
          overridden are mentioned in this document.  Most (if not all)
	  are documented at the start of <filename>bsd.port.mk</filename>;
	  the others probably ought to be.
	  Note that this file uses a non-standard tab setting:
	  <application>Emacs</application> and
	  <application>Vim</application> should recognize the setting on
	  loading the file.  Both &man.vi.1; and

      <title>Quick Porting</title>

      <para>This section tells you how to do a quick port.  In many cases, it
        is not sufficient, so you will have to read further on into
        the document.</para>

      <para>First, get the original tarball and put it into
        <makevar>DISTDIR</makevar>, which defaults to

          <filename>pkg-descr</filename> and
          <filename>pkg-plist</filename>.  Their
          <filename>pkg-</filename> prefix distinguishes them from
          other files.  (Note: the former
          <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>

            make sure all  the stages up to that one are completed and call
            the real targets or scripts, and they are not intended to be
            changed.  If you want to fix the extraction, fix
            <maketarget>do-extract</maketarget>, but never ever change
            the way <maketarget>extract</maketarget> operates!</para>
        </note>

        <para>Now that you understand what goes on when the user types

          <emphasis>mainstream</emphasis> sources when and where you
          can.</para>

        <para>You will need to set the variable <makevar>MASTER_SITES</makevar>
          to reflect where the original tarball resides.  You will find
          convenient shorthand definitions for most mainstream sites
          in <filename>bsd.sites.mk</filename>.  Please use these
          sites&mdash;and the associated definitions&mdash;if
          at all possible, to help avoid the problem of having the same
          information repeated over again many times in the source base.
          As these sites tend to change over time, this becomes a
          maintainence nightmare for everyone involved.</para>

        <para>If you cannot find a FTP/HTTP site that is well-connected to the
          net, or can only find sites that have irritatingly non-standard
          formats, you might want to put a copy on a reliable FTP or HTTP
          server that you control (e.g., your home page).</para>
          <makevar>MASTER_SITES</makevar> to reflect your choice.</para>

        <para>If you cannot find somewhere convenient and reliable to put the
          distfile
          we can <quote>house</quote> it ourselves
          on <hostid>ftp.FreeBSD.org</hostid>; however, this is the
          least-preferred solution, as files housed there tend to get stale.
          The distfile must be placed into
          <filename>~/public_distfiles/</filename> of someone's
          <hostid>freefall</hostid> account.

          <makevar>MASTER_SITE_SUBDIR</makevar> to their
          <hostid>freefall</hostid> username.</para>

        <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>.  (It is too bad we
          cannot always talk port authors out of doing this, because it
          really helps to establish some kind of source code control, but
          alas this is not always easy).   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
          there is only one master site for the port, it is recommended that


        <para>In the preparation of the port, files that have been added or
          changed can be picked up with a recursive &man.diff.1;
          for later feeding to &man.patch.1;.
          Each set of patches you wish to apply should be collected
          into a file named
          <filename>patch-<replaceable>*</replaceable></filename> where
          <replaceable>*</replaceable> denotes the sequence in which the
          patches will be applied &mdash; these are done in

        <title>Handling user input</title>

        <para>If your port requires user input to build, configure, or install,
          you must set <makevar>IS_INTERACTIVE</makevar> in your Makefile.  This
          will allow <quote>overnight builds</quote> to skip your port if the
          user sets the variable <envar>BATCH</envar> in his environment (and
          if the user sets the variable <envar>INTERACTIVE</envar>, then
          <emphasis>only</emphasis> those ports requiring interaction are
          built).  This will save a lot of wasted time on the set of
          machines that continually build ports (see below).</para>

        <para>It is also recommended that if there are reasonable default
          answers to the questions, you check the

        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>


	  </itemizedlist>

	  <para>A rule of thumb is to ask yourself whether a change
	    committed to a port is something which everyone
	    would benefit from having (either because of an
	    enhancement, fix, or by virtue that the new package will
	    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 so that
	    automated tools (e.g.  &man.pkg.version.1;)
	    will highlight the fact that a new package is

	    <makevar>PORTEPOCH</makevar> version should be increased.
	    If <makevar>PORTEPOCH</makevar> is nonzero it is appended
	    to the package name as described in section 0 above.
	    <makevar>PORTEPOCH</makevar> must never be decreased or reset
	    to zero, because that would cause comparison to a package
	    from an earlier epoch to fail (i.e. the package would not
	    be detected as out of date): the new version number (e.g.

	    automated tools and found to be greater than the implied
	    suffix <literal>,0</literal> on the earlier package.</para>

	  <para>Dropping or resetting <makevar>PORTEPOCH</makevar>
	    incorrectly is a common error in the ports collection and 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>

	  <para>It is expected that <makevar>PORTEPOCH</makevar> will
	    not be used for the majority of ports, and that sensible
	    use of <makevar>PORTVERSION</makevar> can often pre-empt

	    <literal>0.1.0</literal>, not <quote>what comes after
	      0.9</quote> - oops, too late now). Since the new minor
	    version <literal>2</literal> is numerically less than the
	    previous version <literal>10</literal>, the
	    <makevar>PORTEPOCH</makevar> must be bumped to manually
	    force the new package to be detected as <quote>newer</quote>. Since it
	    is a new vendor release of the code,

              installed the <literal>gtkmumble-0.10_1</literal> package would not detect
              the <literal>gtkmumble-0.3</literal> package as newer, since
              <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>

          <literal>${PKGNAMEPREFIX}${PORTNAME}${PKGNAMESUFFIX}-${PORTVERSION}</literal>.
          Make sure this conforms to our <link
          linkend="porting-pkgname">guidelines for a good package
          name</link>.  In particular, you are <emphasis>not</emphasis> allowed to use a
          hyphen (<literal>-</literal>) in
          <makevar>PORTVERSION</makevar>.  Also, if the package name
          has the <replaceable>language-</replaceable> or the
          <replaceable>-compiled.specifics</replaceable> part (see below), use
          <makevar>PKGNAMEPREFIX</makevar> and
          <makevar>PKGNAMESUFFIX</makevar>, respectively.  Do not make
          them part of <makevar>PORTNAME</makevar>.</para>


      <para>The following are the conventions you should follow in naming your
        packages.  This is to have our package directory easy to scan, as
        there are already thousands of packages and users are going to
        turn away if they hurt their eyes!</para>

      <para>The package name should look like

        <para>If your port truly belongs to something that is different from
          all the existing ones, you can even create a new category name.  In
          that case, please send mail to the &a.ports; to propose a new
          category.  However, in general, until there are more than a
          handful of ports which could be reclassified into the category
          you propose, you will probably be turned down.</para>

        <para>(Aside: occasionally someone proposes redoing the categories
          as either a 2-level structure, or some other kind of keyword
          structure.  To date, nothing has come of any of these proposals,
          because while they are very easy to make, the effort involved to
          retrofit the entire existing ports collection with any kind of
          reorganization is daunting to say the very least.  Please read
          the history of these proposals in the past mailing lists before
          you post this idea; further, you should be prepared to be
          challenged to offer some kind of working prototype.)</para>
      </sect2>

      <sect2 id="porting-categories">
        <title>Current list of categories</title>

        <para>Here is the current list of port categories.  Those
          marked with an asterisk (<literal>*</literal>) are
          <emphasis>virtual</emphasis> categories&mdash;those that do not have
          a corresponding subdirectory in the ports tree.  They are only
          used as secondary categories, and only for search purposes.</para>

        <note>
          <para>For non-virtual categories, you will find a one-line


              <row>
                <entry><filename>afterstep*</filename></entry>
                <entry>Ports to support the
                  <ulink url="http://www.afterstep.org">
                  AfterStep</ulink> window manager.</entry>
              </row>

              <row>


              <row>
                <entry><filename>comms</filename></entry>
                <entry>Communication software.  (Mostly software to talk to
                  your serial port.)</entry>
              </row>

              <row>


              <row>
                <entry><filename>devel</filename></entry>
                <entry>Development utilities.  (Note: do not put libraries here just
                  because they are libraries&mdash;unless they truly do not
                  belong anywhere else, they should not be in this
                  category.)</entry>
              </row>

              <row>
                <entry><filename>editors</filename></entry>
                <entry>General editors.  (Specialized editors go in the section
                  for those tools (e.g., a mathematical-formula editor will go
                  in <filename>math</filename>) ).</entry>
              </row>

              <row>


              <row>
                <entry><filename>emulators</filename></entry>
                <entry>Emulators for other operating systems.  (Terminal
                  emulators do <emphasis>not</emphasis> belong
                  here&mdash;X-based ones should go to
                  <filename>x11</filename> and text-based ones to either
                  <filename>comms</filename> or <filename>misc</filename>,
                  depending on the exact functionality.)</entry>
              </row>

              <row>


              <row>
                <entry><filename>ftp</filename></entry>
                <entry>FTP client and server utilities.  (If your
                  port speaks both FTP and HTTP, put it in
                  <filename>ftp</filename> with a secondary
                  category of <filename>www</filename>.)</entry>
              </row>

              <row>


              <row>
                <entry><filename>gnome*</filename></entry>
                <entry>Ports from the
                  <ulink url="http://www.gnome.org">GNOME
                  project</ulink>.</entry>
              </row>

              <row>


              <row>
                <entry><filename>kde*</filename></entry>
                <entry>Ports from the
                  <ulink url="http://www.kde.org">K Desktop Environment (KDE)
                  Project</ulink>.</entry>
              </row>

              <row>

              <row>
                <entry><filename>misc</filename></entry>
                <entry>Miscellaneous utilities&mdash;basically things that
                  do not belong anywhere else.  (This is the only category
                  that should not appear with any other non-virtual category.
                  If you have <literal>misc</literal> with something else in
                  your <makevar>CATEGORIES</makevar> line, that means you can
                  safely delete <literal>misc</literal> and just put the port
                  in that other subdirectory!  Also note: if at all possible,
                  try to find a better category for your port than
                  <filename>misc</filename>; ports tend to get overlooked
                  in here.)</entry>
              </row>

              <row>


              <row>
                <entry><filename>offix*</filename></entry>
                <entry>Ports from the
                  <ulink url="http://leb.net/OffiX/">OffiX</ulink> suite.</entry>
              </row>

              <row>
                <entry><filename>palm</filename></entry>
                <entry>Software support for the
                  <ulink url="http://www.palm.com/">Palm(tm)</ulink> series.</entry>
              </row>

              <row>


              <row>
                <entry><filename>perl5*</filename></entry>
                <entry>Ports that require <command>perl</command> version 5 to run.</entry>
              </row>

              <row>
                <entry><filename>picobsd</filename></entry>
                <entry>Ports to support
                  <ulink url="http://people.FreeBSD.org/~picobsd/">
                  PicoBSD</ulink>.</entry>
              </row>

              <row>
                <entry><filename>plan9*</filename></entry>
                <entry>Various programs from
                  <ulink url="http://www.cs.bell-labs.com/plan9dist/">
                  Plan9</ulink>.</entry>
              </row>

              <row>


              <row>
                <entry><filename>print</filename></entry>
                <entry>Printing software.  (Desktop publishing tools
                  (previewers, etc.) belong here too.)</entry>
              </row>

              <row>
                <entry><filename>python*</filename></entry>
                <entry>Software related to the
                  <ulink url="http://www.python.org/">Python</ulink>
                   language.</entry>
              </row>

              <row>


              <row>
                <entry><filename>textproc</filename></entry>
                <entry>Text processing utilities.  (This does not include
                  desktop publishing tools, which should go to
                  <filename>print</filename>.)</entry>
              </row>

              <row>


              <row>
                <entry><filename>www</filename></entry>
                <entry>Software related to the World Wide Web.  (HTML language
                  support belongs here too.)</entry>
              </row>

              <row>
                <entry><filename>x11</filename></entry>
                <entry>The X Window System and friends.  (This category is only
                  for software that directly supports the window system.  Do not
                  put regular X applications here; most of them should go
                  into other <filename>x11-*</filename> categories (see below).
                  Note: if your port <emphasis>is</emphasis> an X
                  application, define <makevar>USE_XLIB</makevar> (implied by
                  <makevar>USE_IMAKE</makevar>) ).</entry>
                  categories.  Also, many of them go into other
                  <filename>x11-*</filename> categories (see below).</entry>
              </row>

              <row>


              <row>
                <entry><filename>zope*</filename></entry>
                <entry><ulink url="http://www.zope.org/">Zope</ulink>
                   support.</entry>
              </row>
            </tbody>
          </tgroup>

          <listitem>
            <para>Specific categories win over less-specific ones.  For
              instance, an HTML editor should be listed as <filename>www
                editors</filename>, not the other way around.  Also, you should
              not list <filename>net</filename> when the port belongs to
              any of <filename>irc</filename>, <filename>mail</filename>,
              <filename>mbone</filename>, <filename>news</filename>,
              <filename>security</filename>, or <filename>www</filename>, as
              <filename>net</filename> is included implicitly.</para>
          </listitem>

          <listitem>

        <para>If you are not sure about the category, please put a comment to
          that effect in your &man.send-pr.1; submission so we can
          discuss it before we import it.  If you are a committer, send a note
          to the &a.ports; so we can discuss it first.  Too often, new ports are
          imported to the wrong category only to be moved right away.
          This causes unneccessary, and undesired, bloat in the master
          source repository.</para>
      </sect2>
    </sect1>



        <para>It is recommended that you put multiple sites on this list,
          preferably from different continents.  This will safeguard against
          wide-area network problems.  (We are hoping to add support
          for automatically determining the closest master site and fetching
          from there in the future; having multiple sites will go
          a long way towards helping this effort.)</para>

        <para>If the original tarball is part of one of the popular
          archives such as X-contrib, GNU, or Perl CPAN, you may be able

	  neither of these are set then <makevar>EXTRACT_SUFX</makevar>
	  defaults to <literal>.tar.gz</literal>.</para>

        <note>
	  <para>You never need to set both <makevar>EXTRACT_SUFX</makevar> and
	    <makevar>DISTFILES</makevar>.</para>
        </note>
      </sect2>

      <sect2>

	  sites and subdirectories
	  (<literal>MASTER_SITES:n</literal>)</title>

	<para>(Consider this to be a somewhat <quote>advanced topic</quote>;
	  those new to this document may wish to skip this section at first).
	  </para>

	<para>This section has information on the fetching mechanism
	  known as both <literal>MASTER_SITES:n</literal> and
	  <literal>MASTER_SITES_NN</literal>.  We will refer to this

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

        <para>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
          into your <filename>pkg-descr</filename>.</para>

        <para>For a detailed description of the responsibilities of maintainers,
          refer to the <ulink url="../developers-handbook/policies.html#POLICIES-MAINTAINER">MAINTAINER on
            Makefiles</ulink> section.</para>

        <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, end without a period, and
          should not be surrounded by quotes.  Here
          is an example:</para>

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

          <para>When you type <command>make clean</command>, its dependencies
            are automatically cleaned too.  If you do not wish this to happen,
            define the variable <makevar>NOCLEANDEPENDS</makevar> in your
            environment.  This may be particularly desireable if the
            port has something that takes a long time to rebuild in its
            dependency list, such as KDE, GNOME, Apache, and so forth.</para>

          <para>To depend on another port unconditionally, use the
            variable <makevar>${NONEXISTENT}</makevar> as the first field 

	<makevar>WANT_IMLIB</makevar>, and
	<makevar>WANT_GNOME</makevar>.</para>
      </sect2>

      <sect2>
        <title>Circular dependencies are fatal</title>

        <important>
          <para>Do not introduce any circular dependencies into the
          ports tree!</para>
        </important>

        <para>The ports building technology does not tolerate
          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, especially with,
          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
          save a large number of people&mdash;including yourself&mdash;
          a lot of grief in the process.</para>
      </sect2>
    </sect1>

    <sect1 id="makefile-wrkdir">
      <title>Specifying the working directory</title>

      <para>Each port is extracted in to a working directory, which must be
	writable.  The ports system defaults to having the
	<makevar>DISTFILES</makevar> unpack in to a directory called
	<literal>${DISTNAME}</literal>.  In other words, if you have
	set:</para>

	<filename>foo-1.0</filename>, and the rest of the files are located
	under that directory.</para>

      <para>There are a number of variables you can override if that is not the
	case.</para>

      <sect2>


	<para>This variable indicates that although we are allowed to generate
	  binary packages, we are not allowed to put those packages, or the
	  port's <makevar>DISTFILES</makevar>, onto a CDROM (or DVD-ROM)
	  for resale.  The
	  <makevar>DISTFILES</makevar> will still be available via FTP
	  (or HTTP if you set it up that way.)</para>

	<para><makevar>NO_PACKAGE</makevar> and <makevar>NO_CDROM</makevar>
	  can be set simultaneously.</para>


	<para>Set this variable if the application's license also forbids us
	  from mirroring the application's <makevar>DISTFILES</makevar> via
	  FTP (or HTTP if you set it up that way.)</para>

	<para>Also set this if the application's license has general
	  restrictions on who may use it, e.g. the application is for
	  non-commercial use only.</para>

	<para>Note that the port committer should add an entry to
	  <filename>/usr/ports/LEGAL</filename> describing exactly
	  what the restriction entails.</para>
      </sect2>

      <sect2>

    <sect1 id="using-bison">
      <title>Using Bison</title>

      <para>This section is yet to be written.</para>
    </sect1>

    <sect1 id="using-java">
      <title>Using Java</title>

      <para>This section is yet to be written.</para>
    </sect1>

    <sect1 id="using-python">
      <title>Using Python</title>

      <para>This section is yet to be written.</para>
    </sect1>

    <sect1 id="using-emacs">
      <title>Using Emacs</title>

      <para>This section is yet to be written.</para>
    </sect1>

    <sect1 id="using-ruby">
      <title>Using Ruby</title>

      <para>This section is yet to be written.</para>
    </sect1>
    </chapter>



        <para>This variable will be set by <filename>bsd.port.mk</filename> to
          be the appropriate reference to the Motif library.  Please patch the
          source of your port to reference this wherever the Motif library
          is referenced in the
          <filename>Makefile</filename> or
          <filename>Imakefile</filename>.</para>



      <para>If your port installs fonts for the X Window System, put them in
        <filename><makevar>X11BASE</makevar>/lib/X11/fonts/local</filename>.
        This directory was new to <application>XFree86 3.3.3</application>.  If it does not exist,
        please create it, and print out a message urging the user to update
        their <application>XFree86</application> to 3.3.3 or newer, or at least add this directory to the
        font path in <filename>/etc/XF86Config</filename>.</para>

          is installed with &man.pkg.add.1; you can do this via the
          <filename>pkg-install</filename> script.  This script will
          automatically be added to the package, and will be run twice by
          &man.pkg.add.1;: the first time as
          <literal>&dollar;{SH} pkg-install &dollar;{PKGNAME}
          PRE-INSTALL</literal> and the second time as
          <literal>&dollar;{SH} pkg-install &dollar;{PKGNAME} POST-INSTALL</literal>. 

          <literal>%%PERL_VERSION%%</literal> will be substituted for
          appropriately.  The value of <literal>%%OSREL%%</literal> is the
          numeric revision of the operating system (e.g.,
          <literal>4.8</literal>).  <literal>%%PERL_VERSION%%</literal> is
          the full version number of <command>perl</command> (e.g.,
          <literal>5.00502</literal>)
          and <literal>%%PERL_VER%%</literal> is the <command>perl</command>
          version number minus
          the patchlevel (e.g., <literal>5.005</literal>).</para>


          set, in which case it will be <makevar>X11BASE</makevar> (default
          <filename>/usr/X11R6</filename>).</para>

        <para>Avoiding hard-coding <filename>/usr/local</filename> or
          <filename>/usr/X11R6</filename> anywhere in the source will make the
          port much more flexible and able to cater to the needs of other
          sites.  For X ports that use <command>imake</command>, this is

      <sect1 id="testing-freshports">
	<title>FreshPorts sanity tests</title>

	<para><ulink url="http://www.FreshPorts.org/"></ulink> has
	  a sanity test feature which automatically tests each commit to the
	  FreeBSD ports tree.  If subscribed to this service, you will be
	  notified of any errors which FreshPorts detects during sanity

        doing a commit.  If the diff is more than about 20KB, please compress
        and uuencode it; otherwise, just include it in the PR as is.</para>

      <para>Finally, please see the
        <ulink url="../../articles/problem-reports/pr-writing.html">
        Writing the problem report</ulink> section in the Problem
        Reports article for more information about how to write
        useful problem reports.</para>

      <important>
	<para>If your upgrade is motivated by security concerns or a
	  serious fault in the currently committed port, please notify

    <chapter id="porting-dads">
      <title>Dos and Don'ts</title>

      <sect1 id="dads-intro">
        <title>Introduction</title>

      <para>Here is a list of common dos and don'ts that you encounter during
        the porting process.  You should check your own port against this list,
        but you can also check ports in the
        <ulink url="http://www.freebsd.org/cgi/query-pr-summary.cgi?query">
        PR database</ulink> that others have
        submitted.  Submit any comments on ports you check as described in
        <ulink url="../../articles/contributing/contrib-how.html#CONTRIB-GENERAL">Bug Reports and General
          Commentary</ulink>.  Checking ports in the PR database will both make
        it faster for us to commit them, and prove that you know what you are
        doing.</para>
      </sect1>

      <sect1 id="dads-strip">
        <title>Stripping Binaries</title>

          <makevar>WRKDIR</makevar>.  <makevar>WRKDIR</makevar> is the only
          place that is guaranteed to be writable during the port build (see
          <ulink url="../handbook/ports-using.html#PORTS-CD">
          installing ports from a CDROM</ulink> for an
          example of building ports from a read-only tree).  If you need to
          modify one of the <filename>pkg-<replaceable>*</replaceable></filename>
          files, do so by <link

          compilation based upon what version of Unix it is running under.  If
          you need to make such changes to the code for conditional
          compilation, make sure you make the changes as general as possible
          so that we can back-port code to older FreeBSD systems and cross-port
          to other BSD systems such as 4.4BSD from CSRG, BSD/386, 386BSD,
          NetBSD, and OpenBSD.</para>


          <listitem>
            <para>In FreeBSD 2.x, <literal>__FreeBSD__</literal> is defined to
              be <literal>2</literal>.  In earlier versions, it is
              <literal>1</literal>.  Later versions always bump it to match
              their major version number.</para>
          </listitem>

          <listitem>
            <para>If you need to tell the difference between a FreeBSD 1.x
              system and a FreeBSD 2.x or above system, usually the right answer
              is to use the <literal>BSD</literal> macros described above.  If
              there actually is a FreeBSD specific change (such as special
              shared library options when using <command>ld</command>) then it


              <row>
                <entry><makevar>OSVERSION</makevar></entry>
                <entry>The numeric version of the operating system; same as
                  <link
                    linkend="freebsd-versions"><literal>__FreeBSD_version</literal></link>.</entry>
              </row>

              <row>
                <entry><makevar>PORTOBJFORMAT</makevar></entry>
                <entry>The object format of the system
                  (<literal>elf</literal> or <literal>aout</literal>;
                  note that for <quote>modern</quote> versions of FreeBSD,
                  <literal>aout</literal> is deprecated.)</entry>
              </row>

              <row>

.if ${PORTOBJFORMAT} == "aout"
       ${LN} -sf liblinpack.so.1.0 ${PREFIX}/lib/liblinpack.so
.endif</programlisting>

        <para>You did remember to use tab instead of spaces after
          <literal>BROKEN=</literal> and
          <literal>TCL_LIB_FILE=</literal>, did you not?
          <!-- smiley -->:-).</para>
      </sect1>

      <sect1 id="dads-documentation">

          the subdirectory with the port's name, which is incorrect.  Also,
          many ports put everything except binaries, header files and manual
          pages in the a subdirectory of <filename>lib</filename>, which does
          not work well with the BSD paradigm.  Many of the files should be
          moved to one of the following: <filename>etc</filename>
          (setup/configuration files), <filename>libexec</filename>
          (executables started internally), <filename>sbin</filename>

          other ports.  This is the current list of UIDs between 50 and
          999.</para>

        <programlisting>bind:*:53:53:Bind Sandbox:/:/sbin/nologin
majordom:*:54:54:Majordomo Pseudo User:/usr/local/majordomo:/nonexistent
cyrus:*:60:60:the cyrus mail server:/nonexistent:/nonexistent
gnats:*:61:1:GNATS database owner:/usr/local/share/gnats/gnats-db:/bin/sh
uucp:*:66:66:UUCP pseudo-user:/var/spool/uucppublic:/usr/libexec/uucp/uucico

          <makevar>EXTRACT*</makevar> instead, and using
          <makevar>GNU_CONFIGURE</makevar> instead of <literal>CONFIGURE_ARGS
            += --prefix=&dollar;{PREFIX}</literal>.</para>

        <para>If you find yourself having to write a whole lot of lines
          of new code to try to do something, please go back and review
          <filename>bsd.port.mk</filename> to see if it contains an
          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.  There is almost nothing in
          <filename>bsd.port.mk</filename> which was included by
          accident and is not continually being worked on.</para>
      </sect1>

      <sect1 id="dads-cc">

	  <makevar>CXX</makevar></title>

	<para>The port should respect both <makevar>CC</makevar>
	  and <makevar>CXX</makevar> variables.  What we mean by this
	  is that the port should not set the values of these variables
	  absolutely, overriding existing values; instead, it should append
	  whatever values it needs to the existing values.  This is so that
	  build options that affect all ports can be set globally.</para>

	<para>If the port does not respect these variables,
	  please add <literal>NO_PACKAGE=ignores either cc or
	  cxx</literal> to the <filename>Makefile</filename>.</para>


        <title>Respect <makevar>CFLAGS</makevar></title>

        <para>The port should respect the <makevar>CFLAGS</makevar> variable.
	  Again, what we mean by this
	  is that the port should not set the value of this variable
	  absolutely, overriding the existing value; instead, it should append
	  whatever values it needs to the existing value.  This is so that
	  build options that affect all ports can be set globally.</para>

	<para>Again, if it does not, please add <literal>NO_PACKAGE=ignores
            cflags</literal> to the <filename>Makefile</filename>.</para>

	<para>An example of a <filename>Makefile</filename> respecting


      <para>Other resources to assist port maintainers include a list of
	<ulink url="http://bento.FreeBSD.org/">package building logs and
	errors</ulink> hosted on the <literal>bento cluster</literal>,
	and also the <ulink
	  url="http://people.FreeBSD.org/~fenner/portsurvey/">FreeBSD
	  Ports distfiles survey</ulink>.</para>
    </chapter>

Return to bug 53422