diff options
Diffstat (limited to 'en_US.ISO8859-1/books/porters-handbook/order')
| -rw-r--r-- | en_US.ISO8859-1/books/porters-handbook/order/Makefile | 15 | ||||
| -rw-r--r-- | en_US.ISO8859-1/books/porters-handbook/order/chapter.xml | 551 |
2 files changed, 0 insertions, 566 deletions
diff --git a/en_US.ISO8859-1/books/porters-handbook/order/Makefile b/en_US.ISO8859-1/books/porters-handbook/order/Makefile deleted file mode 100644 index 6e262d209e..0000000000 --- a/en_US.ISO8859-1/books/porters-handbook/order/Makefile +++ /dev/null @@ -1,15 +0,0 @@ -# -# Build the Porters Handbook with just the content from this chapter. -# -# $FreeBSD$ -# - -CHAPTERS= order/chapter.xml - -VPATH= .. - -MASTERDOC= ${.CURDIR}/../${DOC}.${DOCBOOKSUFFIX} - -DOC_PREFIX?= ${.CURDIR}/../../../.. - -.include "../Makefile" diff --git a/en_US.ISO8859-1/books/porters-handbook/order/chapter.xml b/en_US.ISO8859-1/books/porters-handbook/order/chapter.xml deleted file mode 100644 index 2d09e66c6d..0000000000 --- a/en_US.ISO8859-1/books/porters-handbook/order/chapter.xml +++ /dev/null @@ -1,551 +0,0 @@ -<?xml version="1.0" encoding="iso-8859-1"?> -<!-- - The FreeBSD Documentation Project - - $FreeBSD$ ---> - -<chapter xmlns="http://docbook.org/ns/docbook" - xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" - xml:id="porting-order"> - - <title>Order of Variables in Port Makefiles</title> - - <para>The first sections of the <filename>Makefile</filename> - must always come in the same order. This standard makes it so - everyone can easily read any port without having to search for - variables in a random order.</para> - - <para>The first line of a <filename>Makefile</filename> is always - a comment containing the <application>Subversion</application> - version control ID, followed by an empty line. In new ports, it - looks like this:</para> - - <programlisting># $FreeBSD$ - </programlisting> - - <para>In existing ports, <application>Subversion</application> - has expanded it to look like this:</para> - - <programlisting># $FreeBSD: head/ports-mgmt/pkg/Makefile 437007 2017-03-26 21:25:47Z bapt $ - </programlisting> - - <note> - <para>The sections and variables described here are mandatory in - a ordinary port. In a slave port, many sections and variables - can be skipped.</para> - </note> - - <important> - <para>Each following block must be separated from the previous - block by a single blank line.</para> - - <para>In the following blocks, only set the variables that are - required by the port. Define these variables in the order - they are shown here.</para> - </important> - - <sect1 xml:id="porting-order-portname"> - <title><varname>PORTNAME</varname> Block</title> - - <para>This block is the most important. It defines the port - name, version, distribution file location, and category. The - variables must be in this order:</para> - - <itemizedlist> - <listitem> - <para><link - linkend="makefile-portname"><varname>PORTNAME</varname></link></para> - </listitem> - - <listitem> - <para><link - linkend="makefile-versions"><varname>PORTVERSION</varname></link><footnote - xml:id="portversion-footnote"><important><para>Only one of - <varname>PORTVERSION</varname> and - <varname>DISTVERSION</varname> can be - used.</para></important></footnote></para> - </listitem> - - <listitem> - <para><link - linkend="makefile-versions"><varname>DISTVERSIONPREFIX</varname></link></para> - </listitem> - - <listitem> - <para><link - linkend="makefile-versions"><varname>DISTVERSION</varname></link><footnoteref - linkend="portversion-footnote"/></para> - </listitem> - - <listitem> - <para><link - linkend="makefile-versions"><varname>DISTVERSIONSUFFIX</varname></link></para> - </listitem> - - <listitem> - <para><link - linkend="makefile-portrevision"><varname>PORTREVISION</varname></link></para> - </listitem> - - <listitem> - <para><link - linkend="makefile-portepoch"><varname>PORTEPOCH</varname></link></para> - </listitem> - - <listitem> - <para><link - linkend="makefile-categories"><varname>CATEGORIES</varname></link></para> - </listitem> - - <listitem> - <para><link - linkend="makefile-master_sites"><varname>MASTER_SITES</varname></link></para> - </listitem> - - <listitem> - <para><link - linkend="makefile-master_sites-shorthand"><varname>MASTER_SITE_SUBDIR</varname></link> - (deprecated)</para> - </listitem> - - <listitem> - <para><link - linkend="porting-pkgnameprefix-suffix"><varname>PKGNAMEPREFIX</varname></link></para> - </listitem> - - <listitem> - <para><link - linkend="porting-pkgnameprefix-suffix"><varname>PKGNAMESUFFIX</varname></link></para> - </listitem> - - <listitem> - <para><link - linkend="makefile-distname"><varname>DISTNAME</varname></link></para> - </listitem> - - <listitem> - <para><link - linkend="makefile-extract_sufx"><varname>EXTRACT_SUFX</varname></link></para> - </listitem> - - <listitem> - <para><link - linkend="makefile-distfiles-definition"><varname>DISTFILES</varname></link></para> - </listitem> - - <listitem> - <para><link - linkend="makefile-dist_subdir"><varname>DIST_SUBDIR</varname></link></para> - </listitem> - - <listitem> - <para><link - linkend="makefile-extract_only"><varname>EXTRACT_ONLY</varname></link></para> - </listitem> - </itemizedlist> - </sect1> - - <sect1 xml:id="porting-order-patch"> - <title><varname>PATCHFILES</varname> Block</title> - - <para>This block is optional. The variables are:</para> - - <itemizedlist> - <listitem> - <para><link - linkend="porting-patchfiles"><varname>PATCH_SITES</varname></link></para> - </listitem> - - <listitem> - <para><link - linkend="porting-patchfiles"><varname>PATCHFILES</varname></link></para> - </listitem> - - <listitem> - <para><link - linkend="porting-patchfiles"><varname>PATCH_DIST_STRIP</varname></link></para> - </listitem> - </itemizedlist> - </sect1> - - <sect1 xml:id="porting-order-maintainer"> - <title><varname>MAINTAINER</varname> Block</title> - - <para>This block is mandatory. The variables are:</para> - - <itemizedlist> - <listitem> - <para><link - linkend="makefile-maintainer"><varname>MAINTAINER</varname></link></para> - </listitem> - - <listitem> - <para><link - linkend="makefile-comment"><varname>COMMENT</varname></link></para> - </listitem> - </itemizedlist> - </sect1> - - <sect1 xml:id="porting-order-license"> - <title><varname>LICENSE</varname> Block</title> - - <para>This block is optional, although it is highly recommended. - The variables are:</para> - - <itemizedlist> - <listitem> - <para><link - linkend="licenses-license"><varname>LICENSE</varname></link></para> - </listitem> - - <listitem> - <para><link - linkend="licenses-license_comb"><varname>LICENSE_COMB</varname></link></para> - </listitem> - - <listitem> - <para><link - linkend="licenses-license_groups"><varname>LICENSE_GROUPS</varname></link> - or - <varname>LICENSE_GROUPS_<replaceable>NAME</replaceable></varname></para> - </listitem> - - <listitem> - <para><link - linkend="licenses-license_name"><varname>LICENSE_NAME</varname></link> - or - <varname>LICENSE_NAME_<replaceable>NAME</replaceable></varname></para> - </listitem> - - <listitem> - <para><link - linkend="licenses-license_text"><varname>LICENSE_TEXT</varname></link> - or - <varname>LICENSE_TEXT_<replaceable>NAME</replaceable></varname></para> - </listitem> - - <listitem> - <para><link - linkend="licenses-license_file"><varname>LICENSE_FILE</varname></link> - or - <varname>LICENSE_FILE_<replaceable>NAME</replaceable></varname></para> - </listitem> - - <listitem> - <para><link - linkend="licenses-license_perms"><varname>LICENSE_PERMS</varname></link> - or - <varname>LICENSE_PERMS_<replaceable>NAME</replaceable></varname></para> - </listitem> - - <listitem> - <para><link - linkend="licenses-license_distfiles"><varname>LICENSE_DISTFILES</varname></link> - or - <varname>LICENSE_DISTFILES_<replaceable>NAME</replaceable></varname></para> - </listitem> - </itemizedlist> - - <para>If there are multiple licenses, sort the different - LICENSE_<replaceable>VAR</replaceable>_<replaceable>NAME</replaceable> - variables by license name.</para> - </sect1> - - <sect1 xml:id="porting-order-broken"> - <title>Generic - <varname>BROKEN</varname>/<varname>IGNORE</varname>/<varname>DEPRECATED</varname> - Messages</title> - - <para>This block is optional. The variables are:</para> - - <itemizedlist> - <listitem> - <para><link - linkend="dads-deprecated"><varname>DEPRECATED</varname></link></para> - </listitem> - - <listitem> - <para><link - linkend="dads-deprecated"><varname>EXPIRATION_DATE</varname></link></para> - </listitem> - - <listitem> - <para><link - linkend="dads-noinstall"><varname>FORBIDDEN</varname></link></para> - </listitem> - - <listitem> - <para><link - linkend="dads-noinstall"><varname>BROKEN</varname></link></para> - </listitem> - - <listitem> - <para><link - linkend="dads-noinstall"><varname>BROKEN_<replaceable>*</replaceable></varname></link></para> - </listitem> - - <listitem> - <para><link - linkend="dads-noinstall"><varname>IGNORE</varname></link></para> - </listitem> - - <listitem> - <para><link - linkend="dads-noinstall"><varname>IGNORE_<replaceable>*</replaceable></varname></link></para> - </listitem> - - <listitem> - <para><link - linkend="dads-noinstall"><varname>ONLY_FOR_ARCHS</varname></link></para> - </listitem> - - <listitem> - <para><link - linkend="dads-noinstall"><varname>ONLY_FOR_ARCHS_REASON<replaceable>*</replaceable></varname></link></para> - </listitem> - - <listitem> - <para><link - linkend="dads-noinstall"><varname>NOT_FOR_ARCHS</varname></link></para> - </listitem> - - <listitem> - <para><link - linkend="dads-noinstall"><varname>NOT_FOR_ARCHS_REASON<replaceable>*</replaceable></varname></link></para> - </listitem> - </itemizedlist> - - <note> - <para><varname>BROKEN_<replaceable>*</replaceable></varname> - and <varname>IGNORE_<replaceable>*</replaceable></varname> - can be any generic variables, for example, - <varname>IGNORE_amd64</varname>, - <varname>BROKEN_FreeBSD_10</varname>, etc. With the exception - of variables that depend on a <link - linkend="uses"><varname>USES</varname></link>, place those - in <xref linkend="porting-order-uses"/>. For instance, - <varname>IGNORE_WITH_PHP</varname> only works if - <link linkend="uses-php"><literal>USES=php</literal></link> is - set, and <varname>BROKEN_SSL</varname> only if <link - linkend="uses-ssl"><literal>USES=ssl</literal></link> is - set.</para> - - <para>If the port is marked BROKEN when some conditions are - met, and such conditions can only be tested after including - <filename>bsd.port.options.mk</filename> or - <filename>bsd.port.pre.mk</filename>, then those variables - should be set later, in <xref - linkend="porting-order-rest"/>.</para> - </note> - </sect1> - - <sect1 xml:id="porting-order-depends"> - <title>The Dependencies Block</title> - - <para>This block is optional. The variables are:</para> - - <itemizedlist> - <listitem> - <para><link - linkend="makefile-fetch_depends"><varname>FETCH_DEPENDS</varname></link></para> - </listitem> - - <listitem> - <para><link - linkend="makefile-extract_depends"><varname>EXTRACT_DEPENDS</varname></link></para> - </listitem> - - <listitem> - <para><link - linkend="makefile-patch_depends"><varname>PATCH_DEPENDS</varname></link></para> - </listitem> - - <listitem> - <para><link - linkend="makefile-build_depends"><varname>BUILD_DEPENDS</varname></link></para> - </listitem> - - <listitem> - <para><link - linkend="makefile-lib_depends"><varname>LIB_DEPENDS</varname></link></para> - </listitem> - - <listitem> - <para><link - linkend="makefile-run_depends"><varname>RUN_DEPENDS</varname></link></para> - </listitem> - - <listitem> - <!-- FIXME: write a section about tests --> - <para><varname>TEST_DEPENDS</varname></para> - </listitem> - </itemizedlist> - </sect1> - - <sect1 xml:id="porting-order-flavors"> - <title>Flavors</title> - - <para>This block is optional.</para> - - <para>Start this section with defining <varname>FLAVORS</varname>. - Continue with the possible Flavors helpers. See <xref - linkend="flavors-using"/> for more Information.</para> - - <para>Constructs setting variables not available as helpers using - <literal>.if ${FLAVOR:U} == foo</literal> should go in their - respective sections below.</para> - </sect1> - - <sect1 xml:id="porting-order-uses"> - <title><varname>USES</varname> and - <varname>USE_<replaceable>x</replaceable></varname></title> - - <para>Start this section with defining <varname>USES</varname>, - and then possible - <varname>USE_<replaceable>x</replaceable></varname>.</para> - - <para>Keep related variables close together. For example, if - using <link - linkend="makefile-master_sites-github"><varname>USE_GITHUB</varname></link>, - always put the - <varname>GH_<replaceable>*</replaceable></varname> variables - right after it.</para> - </sect1> - - <sect1 xml:id="porting-order-variables"> - <title>Standard <filename>bsd.port.mk</filename> Variables</title> - - <para>This section block is for variables that can be defined in - <filename>bsd.port.mk</filename> that do not belong in any - of the previous section blocks.</para> - - <para>Order is not important, however try to keep similar - variables together. For example uid and gid variables - <varname>USERS</varname> and <varname>GROUPS</varname>. - Configuration variables - <varname>CONFIGURE_<replaceable>*</replaceable></varname> and - <varname><replaceable>*</replaceable>_CONFIGURE</varname>. List - of files, and directories <varname>PORTDOCS</varname> and - <varname>PORTEXAMPLES</varname>.</para> - </sect1> - - <sect1 xml:id="porting-order-options"> - <title>Options and Helpers</title> - - <para>If the port uses the <link - linkend="makefile-options">options framework</link>, define - <varname>OPTIONS_DEFINE</varname> and - <varname>OPTIONS_DEFAULT</varname> first, then the other - <varname>OPTIONS_<replaceable>*</replaceable></varname> - variables first, then the - <varname><replaceable>*</replaceable>_DESC</varname> - descriptions, then the options helpers. Try and sort all of - those alphabetically.</para> - - <example xml:id="porting-order-options-ex1"> - <title>Options Variables Order Example</title> - - <para>The <literal>FOO</literal> and <literal>BAR</literal> - options do not have a standard description, so one need to - be written. The other options already have one in - <filename>Mk/bsd.options.desc.mk</filename> so writing one - is not needed. The <literal>DOCS</literal> and - <literal>EXAMPLES</literal> use target helpers to install - their files, they are shown here for completeness, though - they belong in <xref linkend="porting-order-targets"/>, so - other variables and targets could be inserted before - them.</para> - - <programlisting>OPTIONS_DEFINE= DOCS EXAMPLES FOO BAR -OPTIONS_DEFAULT= FOO -OPTIONS_RADIO= SSL -OPTIONS_RADIO_SSL= OPENSSL GNUTLS -OPTIONS_SUB= yes - -BAR_DESC= Enable bar support -FOO_DESC= Enable foo support - -BAR_CONFIGURE_WITH= bar=${LOCALBASE} -FOO_CONFIGURE_ENABLE= foo -GNUTLS_CONFIGURE_ON= --with-ssl=gnutls -OPENSSL_CONFIGURE_ON= --with-ssl=openssl - -post-install-DOCS-on: - ${MKDIR} ${STAGEDIR}${DOCSDIR} - cd ${WRKSRC}/doc && ${COPYTREE_SHARE} . ${STAGEDIR}${DOCSDIR} - -post-install-EXAMPLES-on: - ${MKDIR} ${STAGEDIR}${EXAMPLESDIR} - cd ${WRKSRC}/ex && ${COPYTREE_SHARE} . ${STAGEDIR}${EXAMPLESDIR}</programlisting> - </example> - </sect1> - - <sect1 xml:id="porting-order-rest"> - <title>The Rest of the Variables</title> - - <para>And then, the rest of the variables that are not - mentioned in the previous blocks.</para> - </sect1> - - <sect1 xml:id="porting-order-targets"> - <title>The Targets</title> - - <para>After all the variables are defined, the optional - &man.make.1; targets can be defined. Keep - <literal>pre-<replaceable>*</replaceable></literal> before - <literal>post-<replaceable>*</replaceable></literal> and in - the same order as the different stages run:</para> - - <itemizedlist> - <listitem> - <para><varname>fetch</varname></para> - </listitem> - - <listitem> - <para><varname>extract</varname></para> - </listitem> - - <listitem> - <para><varname>patch</varname></para> - </listitem> - - <listitem> - <para><varname>configure</varname></para> - </listitem> - - <listitem> - <para><varname>build</varname></para> - </listitem> - - <listitem> - <para><varname>install</varname></para> - </listitem> - - <listitem> - <para><varname>test</varname></para> - </listitem> - </itemizedlist> - - <tip> - <para>When using options helpers target keep them alphabetically - sorted, but keep the - <literal><replaceable>*</replaceable>-on</literal> before the - <literal><replaceable>*</replaceable>-off</literal>. When - also using the main target, keep the main target before the - optional ones:</para> - - <programlisting>post-install: - # install generic bits - -post-install-DOCS-on: - # Install documentation - -post-install-X11-on: - # Install X11 related bits - -post-install-X11-off: - # Install bits that should be there if X11 is disabled</programlisting> - </tip> - </sect1> -</chapter> |