Attachment #32289 for bug #53420

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




	  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
	  &man.ex.1; can be set to use the correct value by
	  typing <command>:set tabstop=4</command> once the file has been
	  loaded.</para>
      </note>

          actions are done.</para>

        <para>For example, if you have a <maketarget>post-extract</maketarget>
          target defined in your <filename>Makefile</filename>, and a file
          <filename>pre-build</filename> in the <filename>scripts</filename>
          subdirectory, the <maketarget>post-extract</maketarget> target will
          be called after the regular extraction actions, and the

        <title>Patching</title>

        <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

          <literal>&dollar;RCS</literal>.</para>

        <para>Using the recurse (<option>-r</option>) option to
          &man.diff.1; to generate patches is fine, but please take
          a look at the resulting patches to make sure you do not have any
          unnecessary junk in there.  In particular, diffs between two backup
          files, <filename>Makefile</filename>s when the port uses
          <command>Imake</command> or GNU <command>configure</command>, etc.,
          are unnecessary and should be deleted.  If you had to edit
          <filename>configure.in</filename> and run

        <title>Handling user input</title>

        <para>If your port requires user input to build, configure, or install,
          then set <makevar>IS_INTERACTIVE</makevar> in your <filename>Makefile</filename>.  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

    <chapter id="makefile">
      <title>Configuring the Makefile</title>

      <para>Configuring the <filename>Makefile</filename> is pretty simple, and again we suggest
        that you look at existing examples before starting. Also, there is a
        <link linkend="porting-samplem">sample Makefile</link> in this
        handbook, so take a look and please follow the ordering of variables

        read.</para>

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

      <sect1 id="makefile-source">
        <title>The original source</title>

	    affects the content or structure of the derived
	    package.</para>

	  <para>Examples of when <makevar>PORTREVISION</makevar> should be bumped:</para>

	  <itemizedlist>
	    <listitem>

	    </listitem>

	    <listitem>
	      <para>Changes to the port <filename>Makefile</filename> to enable or disable
		compile-time options in the package.</para>
	    </listitem>


	    enhancement, fix, or by virtue that the new package will
	    actually work for them). 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
	    available.</para>
	</sect3>

	  <title>Example of <makevar>PORTREVISION</makevar> and
	    <makevar>PORTEPOCH</makevar> usage</title>

	  <para>The <literal>gtkmumble</literal> port, version <literal>0.10</literal>, is committed to the
	    ports collection:</para>

	  <programlisting>PORTNAME=	gtkmumble
PORTVERSION=	0.10</programlisting>

	    force the new package to be detected as <quote>newer</quote>. Since it
	    is a new vendor release of the code,
	    <makevar>PORTREVISION</makevar> is reset to 0 (or removed
	    from the <filename>Makefile</filename>).</para>

	  <programlisting>PORTNAME=	gtkmumble
PORTVERSION=	0.2

          <note>
            <para>If <makevar>PORTEPOCH</makevar> were reset
              to <literal>0</literal> with this upgrade, someone who had
              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>.</para>
	  </note>

          hyphen (<literal>-</literal>) in
          <makevar>PORTVERSION</makevar>.  Also, if the package name
          has the <replaceable>language-</replaceable> or the
          <replaceable>-compiled.specifics</replaceable> part, use
          <makevar>PKGNAMEPREFIX</makevar> and
          <makevar>PKGNAMESUFFIX</makevar>, respectively.  Do not make
          them part of <makevar>PORTNAME</makevar>.</para>

            should be lowercase.  (The rest of the name can contain
            capital letters, so use your own discretion when you are
            converting a software name that has some capital letters in it.)
            There is a tradition of naming <literal>perl 5</literal> modules by
            prepending <literal>p5-</literal> and converting the double-colon
            separator to a hyphen; for example, the
            <literal>Data::Dumper</literal> module becomes

            the compiled-in defaults (the hyphen is optional).  Examples are
            papersize and font units.</para>

          <para>The <replaceable>-compiled.specifics</replaceable> part
            should be set in the <makevar>PKGNAMESUFFIX</makevar>
            variable.</para>
        </listitem>

      <para>If there is absolutely no trace of version information in the
        original source and it is unlikely that the original author will ever
        release another version, just set the version string to
        <literal>1.0</literal> (like the <literal>piewm</literal> example above).  Otherwise, ask
        the original author or use the date string
        (<literal><replaceable>yyyy</replaceable>.<replaceable>mm</replaceable>.<replaceable>dd</replaceable></literal>)
	as the version.</para>


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

              <row>

              <row>
                <entry><filename>windowmaker*</filename></entry>
                <entry>Ports to support the WindowMaker window
                  manager.</entry>
              </row>

              <row>


        <note>
          <para>This does not affect the <makevar>MASTER_SITES</makevar> you
            define in your <filename>Makefile</filename>.</para>
        </note>
      </sect2>
    </sect1>

            <maketarget>extract</maketarget> target and then from within the
            <maketarget>install</maketarget> target.  Also, the name of the
            dependency is put into the package so that
            &man.pkg.add.1; will automatically install it if it is
            not on the user's system.</para>
        </sect2>


          <para>The dependency is checked from within the
            <maketarget>install</maketarget> target.  Also, the name of the
            dependency is put into the  package so that
            &man.pkg.add.1; will automatically install it if it is
            not on the user's system.  The <replaceable>target</replaceable>
            part can be omitted if it is the same as
            <makevar>DEPENDS_TARGET</makevar>.</para>

	      <row>
		<entry><makevar>USE_PERL5</makevar></entry>

		<entry>The port requires <literal>perl 5</literal> to build and install.  See
		  <xref linkend="using-perl"> for additional variables that
		  can be set relating to <literal>perl</literal>.</entry>
	      </row>

	      <row>

            GNU autoconf to be run.  Define <literal>USE_QT=yes</literal> if
            your port uses the latest qt toolkit.  Use
            <literal>USE_PERL5=yes</literal> if your port requires version 5
            of the <literal>perl</literal> language.  (The last is especially important since
            some versions of FreeBSD have <literal>perl5</literal> as part of the base system
            while others do not.)</para>
        </sect2>



            <programlisting>BUILD_DEPENDS=   ${NONEXISTENT}:${PORTSDIR}/graphics/jpeg:extract</programlisting>

            will always descend to the <literal>jpeg</literal> port and extract it.</para>

          <para>Do not use <makevar>DEPENDS</makevar> unless there is no other
            way the behavior you want can be accomplished.  It will cause the

    </sect1>

    <sect1 id="using-perl">
      <title>Using <literal>perl</literal></title>

      <table frame="none">
	<title>Variables for ports that use <literal>perl</literal></title>

	<tgroup cols="2">
	  <thead>

	    <row>
	      <entry><makevar>USE_PERL5</makevar></entry>

	      <entry>Says that the port uses <literal>perl 5</literal> to build and run.</entry>
	    </row>
	    
	    <row>

	    <row>
	      <entry><makevar>PERL_VERSION</makevar></entry>
	      
	      <entry>The full version of <literal>perl</literal> installed (e.g.,
		<literal>5.00503</literal>).</entry>
	    </row>
	    
	    <row>
	      <entry><makevar>PERL_VER</makevar></entry>
	      
	      <entry>The short version of <literal>perl</literal> installed (e.g.,
		<literal>5.005</literal>).</entry>
	    </row>

            <row>
              <entry><makevar>PERL_LEVEL</makevar></entry>

              <entry>The installed <literal>perl</literal> version as an integer of the form <literal>MNNNPP</literal>
                (e.g., <literal>500503</literal>).</entry>
	    </row>
	    
	    <row>
	      <entry><makevar>PERL_ARCH</makevar></entry>
	      
	      <entry>Where <literal>perl</literal> stores architecture dependent libraries.
		Defaults to <literal>${ARCH}-freebsd</literal>.</entry>
	    </row>
	  </tbody>

      <sect1>
        <title><makevar>LIB_DEPENDS</makevar></title>

        <para>All port <filename>Makefile</filename>s are edited to remove minor numbers from
          <makevar>LIB_DEPENDS</makevar>, and also to have the regexp support
          removed.  (E.g., <literal>foo\\.1\\.\\(33|40\\)</literal> becomes
          <literal>foo.2</literal>.)  They will be matched using <command>grep

      <sect1>
        <title><literal>ldconfig</literal></title>

        <para>The <literal>ldconfig</literal> line in <filename>Makefile</filename>s should
          read:</para>

        <programlisting>${SETENV} OBJFORMAT=${PORTOBJFORMAT} ${LDCONFIG} -m ....</programlisting>

        make it easier for users to see what to do, but try to share as many
        files as possible between ports.  Typically you only need a very short
        <filename>Makefile</filename> in all but one of the directories if you
        use variables cleverly.  In the sole <filename>Makefile</filename>,
        you can use <makevar>MASTERDIR</makevar> to specify the directory
        where the rest of the files are.  Also, use a variable as part of
        <link linkend="porting-pkgname"><makevar>PKGNAMESUFFIX</makevar></link> so

      <para>If your port anchors its man tree somewhere other than
        <makevar>PREFIX</makevar>, you can use the
        <makevar>MANPREFIX</makevar> to set it.  Also, if only manpages in
        certain sections go in a non-standard place, such as some <literal>perl</literal> modules
        ports, you can set individual man paths using
        <makevar>MAN<replaceable>sect</replaceable>PREFIX</makevar> (where
        <replaceable>sect</replaceable> is one of <literal>1-9</literal>,

        <title><makevar>USE_MOTIF</makevar></title>

        <para>If your port requires Motif, define this variable in the
          <filename>Makefile</filename>.  This will prevent people who do not own a copy of Motif
          from even attempting to build it.</para>
      </sect1>


          <para>Edit <filename>pkg-plist</filename> and add equivalent
            <literal>@exec</literal> statements and also
            <literal>@unexec</literal> for
            &man.pkg.delete.1;.</para>

          <programlisting>Index: pkg-plist
===================================================================

        <para>If you need to display a message to the installer, you may place
          the message in <filename>pkg-message</filename>.  This capability is
          often useful to display additional installation steps to be taken
          after a &man.pkg.add.1; or to display licensing
          information.</para>

        <note>

        <title><filename>pkg-install</filename></title>

        <para>If your port needs to execute commands when the binary package
          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>. 

          installation/deinstallation should proceed.</para>

        <para>The script will be run at installation time by
          &man.pkg.add.1; as
          <literal>pkg-req &dollar;{PKGNAME} INSTALL</literal>.
          At deinstallation time it will be run by
          &man.pkg.delete.1; as
          <literal>pkg-req &dollar;{PKGNAME} DEINSTALL</literal>.</para>
      </sect1>


        <title>Changing <filename>pkg-plist</filename> based on make
          variables</title>

        <para>Some ports, particularly the <literal>p5-</literal> ports, need to change their
          <filename>pkg-plist</filename> depending on what options they are
          configured with (or version of <literal>perl</literal>, in the case of <literal>p5-</literal> ports).  To
          make this easy, any instances in the <filename>pkg-plist</filename> of
          <literal>%%OSREL%%</literal>, <literal>%%PERL_VER%%</literal>, and
          <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>2.2.7</literal>).  <literal>%%PERL_VERSION%%</literal> is
          the full version number of <literal>perl</literal> (e.g., <literal>5.00502</literal>)
          and <literal>%%PERL_VER%%</literal> is the <literal>perl</literal> version number minus
          the patchlevel (e.g., <literal>5.005</literal>).</para>

        <para>If you need to make other substitutions, you can set the

          automatic; otherwise, this can often be done by simply replacing the
          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>The variable <makevar>PREFIX</makevar> can be reassigned in your
          <filename>Makefile</filename> or in the user's environment.
          However, it is strongly discouraged for individual ports to set this
          variable explicitly in the <filename>Makefile</filename>s.</para>

        <para>Also, refer to programs/files from other ports with the
          variables mentioned above, not explicit pathnames.  For instance, if

          if this is an X port, instead of
          <literal>-DPAGER=\"/usr/local/bin/less\"</literal>. This way it will
          have a better chance of working if the system administrator has
          moved the whole <filename>/usr/local</filename> tree somewhere else.</para>
      </sect1>

      <sect1 id="testing-freshports">

	  testing of your commits.</para>

	<para>If you wish to use this service, all you need is a FreshPorts
	  account.  If your registered email address is <literal>@FreeBSD.org</literal>,
	  you'll see the opt-in link on the right hand side of the webpages.
	  For those of you who already have a FreshPorts account, but are not
	  using your <literal>@FreeBSD.org</literal> email address, just change your email to
	  <literal>@FreeBSD.org</literal>, subscribe, then change it back again.</para>
      </sect1>
  </chapter>



        <note>
          <para>You need to include either the
            <filename>bsd.port.pre.mk</filename>/<filename>bsd.port.post.mk</filename> pair or
            <filename>bsd.port.mk</filename> only; do not mix these two usages.</para>
        </note>

        <para><filename>bsd.port.pre.mk</filename> only defines a few

          (executables started internally), <filename>sbin</filename>
          (executables for superusers/managers), <filename>info</filename>
          (documentation for info browser) or  <filename>share</filename>
          (architecture independent files).  See &man.hier.7; for details;
          the rules governing
          <filename>/usr</filename> pretty much apply to
          <filename>/usr/local</filename> too.  The exception are ports

        <programlisting>@unexec rmdir %D/share/doc/gimp 2>/dev/null || true</programlisting>

        <para>This will neither print any error messages nor cause
          &man.pkg.delete.1; to exit abnormally even if
          <filename><makevar>PREFIX</makevar>/share/doc/gimp</filename> is not
          empty due to other ports installing some files in there.</para>
      </sect1>

          <filename><makevar>PREFIX</makevar>/etc</filename>, do
          <emphasis>not</emphasis> just install them and list them in
          <filename>pkg-plist</filename>.  That will cause
          &man.pkg.delete.1; to delete files carefully edited by
          the user and a new installation to wipe them out.</para>

        <para>Instead, install sample files with a suffix

	Please use the correct <command>make</command> variable as
	each make variable conveys radically different meanings to
	both users, and to automated systems that parse
	<filename>Makefile</filename>s.</para>

	<itemizedlist>
	  <listitem>

Return to bug 53420