diff options
Diffstat (limited to 'documentation/content/zh-tw/books/porters-handbook/order/_index.adoc')
| -rw-r--r-- | documentation/content/zh-tw/books/porters-handbook/order/_index.adoc | 282 |
1 files changed, 282 insertions, 0 deletions
diff --git a/documentation/content/zh-tw/books/porters-handbook/order/_index.adoc b/documentation/content/zh-tw/books/porters-handbook/order/_index.adoc new file mode 100644 index 0000000000..2f032a678d --- /dev/null +++ b/documentation/content/zh-tw/books/porters-handbook/order/_index.adoc @@ -0,0 +1,282 @@ +--- +title: Chapter 15. Order of Variables in Port Makefiles +prev: books/porters-handbook/porting-samplem +next: books/porters-handbook/keeping-up +description: Order of Variables in FreeBSD Port Makefiles +tags: ["order", "PORTNAME", "PATCHFILES", "MAINTAINER", "LICENSE", "dependencies", "USES"] +showBookMenu: true +weight: 15 +path: "/books/porters-handbook/order/" +--- + +[[porting-order]] += Order of Variables in Port Makefiles +:doctype: book +:toc: macro +:toclevels: 1 +:icons: font +:sectnums: +:sectnumlevels: 6 +:sectnumoffset: 15 +:partnums: +:source-highlighter: rouge +:experimental: +:images-path: books/porters-handbook/ + +ifdef::env-beastie[] +ifdef::backend-html5[] +:imagesdir: ../../../../images/{images-path} +endif::[] +ifndef::book[] +include::shared/authors.adoc[] +include::shared/mirrors.adoc[] +include::shared/releases.adoc[] +include::shared/attributes/attributes-{{% lang %}}.adoc[] +include::shared/{{% lang %}}/teams.adoc[] +include::shared/{{% lang %}}/mailing-lists.adoc[] +include::shared/{{% lang %}}/urls.adoc[] +toc::[] +endif::[] +ifdef::backend-pdf,backend-epub3[] +include::../../../../../shared/asciidoctor.adoc[] +endif::[] +endif::[] + +ifndef::env-beastie[] +toc::[] +include::../../../../../shared/asciidoctor.adoc[] +endif::[] + +The first sections of the [.filename]#Makefile# 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. + +[NOTE] +==== +The sections and variables described here are mandatory in a ordinary port. +In a slave port, many sections and variables can be skipped. +==== + +[IMPORTANT] +==== +Each following block must be separated from the previous block by a single blank line. + +In the following blocks, only set the variables that are required by the port. +Define these variables in the order they are shown here. +==== + +[[porting-order-portname]] +== `PORTNAME` Block + +This block is the most important. It defines the port name, version, distribution file location, and category. +The variables must be in this order: + +* crossref:makefiles[makefile-portname,`PORTNAME`] +* crossref:makefiles[makefile-versions,`PORTVERSION`][<<portversion-footnote, 1>>] +* crossref:makefiles[makefile-versions,`DISTVERSIONPREFIX`] +* crossref:makefiles[makefile-versions,`DISTVERSION`][<<portversion-footnote, 1>>] +* crossref:makefiles[makefile-versions,`DISTVERSIONSUFFIX`] +* crossref:makefiles[makefile-portrevision,`PORTREVISION`] +* crossref:makefiles[makefile-portepoch,`PORTEPOCH`] +* crossref:makefiles[makefile-categories,`CATEGORIES`] +* crossref:makefiles[makefile-master_sites,`MASTER_SITES`] +* crossref:makefiles[makefile-master_sites-shorthand,`MASTER_SITE_SUBDIR`] (deprecated) +* crossref:makefiles[porting-pkgnameprefix-suffix,`PKGNAMEPREFIX`] +* crossref:makefiles[porting-pkgnameprefix-suffix,`PKGNAMESUFFIX`] +* crossref:makefiles[makefile-distname,`DISTNAME`] +* crossref:makefiles[makefile-extract_sufx,`EXTRACT_SUFX`] +* crossref:makefiles[makefile-distfiles-definition,`DISTFILES`] +* crossref:makefiles[makefile-dist_subdir,`DIST_SUBDIR`] +* crossref:makefiles[makefile-extract_only,`EXTRACT_ONLY`] + +[[portversion-footnote]] +[IMPORTANT] +==== +Only one of PORTVERSION and DISTVERSION can be used. +==== + +[[porting-order-patch]] +== `PATCHFILES` Block + +This block is optional. +The variables are: + +* crossref:makefiles[porting-patchfiles,`PATCH_SITES`] +* crossref:makefiles[porting-patchfiles,`PATCHFILES`] +* crossref:makefiles[porting-patchfiles,`PATCH_DIST_STRIP`] + +[[porting-order-maintainer]] +== `MAINTAINER` Block + +This block is mandatory. +The variables are: + +* crossref:makefiles[makefile-maintainer,`MAINTAINER`] +* crossref:makefiles[makefile-comment,`COMMENT`] + +[[porting-order-license]] +== `LICENSE` Block + +This block is optional, although it is highly recommended. +The variables are: + +* crossref:makefiles[licenses-license,`LICENSE`] +* crossref:makefiles[licenses-license_comb,`LICENSE_COMB`] +* crossref:makefiles[licenses-license_groups,`LICENSE_GROUPS`] or `LICENSE_GROUPS_NAME` +* crossref:makefiles[licenses-license_name,`LICENSE_NAME`] or `LICENSE_NAME_NAME` +* crossref:makefiles[licenses-license_text,`LICENSE_TEXT`] or `LICENSE_TEXT_NAME` +* crossref:makefiles[licenses-license_file,`LICENSE_FILE`] or `LICENSE_FILE_NAME` +* crossref:makefiles[licenses-license_perms,`LICENSE_PERMS`] or `LICENSE_PERMS_NAME_` +* crossref:makefiles[licenses-license_distfiles,`LICENSE_DISTFILES`] or `LICENSE_DISTFILES_NAME` + +If there are multiple licenses, sort the different LICENSE_VAR_NAME variables by license name. + +[[porting-order-broken]] +== Generic `BROKEN`/`IGNORE`/`DEPRECATED` Messages + +This block is optional. The variables are: + +* crossref:porting-dads[dads-deprecated,`DEPRECATED`] +* crossref:porting-dads[dads-deprecated,`EXPIRATION_DATE`] +* crossref:porting-dads[dads-noinstall,`FORBIDDEN`] +* crossref:porting-dads[dads-noinstall,`BROKEN`] +* crossref:porting-dads[dads-noinstall,`BROKEN_*`] +* crossref:porting-dads[dads-noinstall,`IGNORE`] +* crossref:porting-dads[dads-noinstall,`IGNORE_*`] +* crossref:porting-dads[dads-noinstall,`ONLY_FOR_ARCHS`] +* crossref:porting-dads[dads-noinstall,`ONLY_FOR_ARCHS_REASON*`] +* crossref:porting-dads[dads-noinstall,`NOT_FOR_ARCHS`] +* crossref:porting-dads[dads-noinstall,`NOT_FOR_ARCHS_REASON*`] + +[NOTE] +==== +`BROKEN_*` and `IGNORE_*` can be any generic variables, for example, `IGNORE_amd64`, `BROKEN_FreeBSD_10`, etc. +With the exception of variables that depend on a crossref:uses[uses,`USES`], place those in <<porting-order-uses>>. +For instance, `IGNORE_WITH_PHP` only works if crossref:uses[xuses-php,`php`] is set, and `BROKEN_SSL` only if crossref:uses[uses-ssl,`ssl`] is set. + +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# or [.filename]#bsd.port.pre.mk#, then those variables should be set later, in <<porting-order-rest>>. +==== + +[[porting-order-depends]] +== The Dependencies Block + +This block is optional. The variables are: + +* crossref:makefiles[makefile-fetch_depends,`FETCH_DEPENDS`] +* crossref:makefiles[makefile-extract_depends,`EXTRACT_DEPENDS`] +* crossref:makefiles[makefile-patch_depends,`PATCH_DEPENDS`] +* crossref:makefiles[makefile-build_depends,`BUILD_DEPENDS`] +* crossref:makefiles[makefile-lib_depends,`LIB_DEPENDS`] +* crossref:makefiles[makefile-run_depends,`RUN_DEPENDS`] +* `TEST_DEPENDS` + +[[porting-order-flavors]] +== Flavors + +This block is optional. + +Start this section with defining `FLAVORS`. +Continue with the possible Flavors helpers. +See crossref:flavors[flavors-using,Using FLAVORS] for more Information. + +Constructs setting variables not available as helpers using `.if ${FLAVOR:U} == foo` should go in their respective sections below. + +[[porting-order-uses]] +== `USES` and `USE_x` + +Start this section with defining `USES`, and then possible `USE_x`. + +Keep related variables close together. +For example, if using crossref:makefiles[makefile-master_sites-github,`USE_GITHUB`], always put the `GH_*` variables right after it. + +[[porting-order-variables]] +== Standard bsd.port.mk Variables + +This section block is for variables that can be defined in [.filename]#bsd.port.mk# that do not belong in any of the previous section blocks. + +Order is not important, however try to keep similar variables together. +For example uid and gid variables `USERS` and `GROUPS`. +Configuration variables `CONFIGURE_*` and `*_CONFIGURE`. +List of files, and directories `PORTDOCS` and `PORTEXAMPLES`. + +[[porting-order-options]] +== Options and Helpers + +If the port uses the crossref:makefiles[makefile-options,options framework], define `OPTIONS_DEFINE` and `OPTIONS_DEFAULT` first, +then the other `OPTIONS_*` variables first, then the `*_DESC` descriptions, then the options helpers. +Try and sort all of those alphabetically. + +[[porting-order-options-ex1]] +.Options Variables Order Example +[example] +==== +The `FOO` and `BAR` 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# so writing one is not needed. +The `DOCS` and `EXAMPLES` use target helpers to install their files, they are shown here for completeness, +though they belong in <<porting-order-targets>>, so other variables and targets could be inserted before them. + +[.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} +.... + +==== + +[[porting-order-rest]] +== The Rest of the Variables + +And then, the rest of the variables that are not mentioned in the previous blocks. + +[[porting-order-targets]] +== The Targets + +After all the variables are defined, the optional man:make[1] targets can be defined. +Keep `pre-*` before `post-*` and in the same order as the different stages run: + +* `fetch` +* `extract` +* `patch` +* `configure` +* `build` +* `install` +* `test` + +[TIP] +==== +When using options helpers target keep them alphabetically sorted, but keep the `*-on` before the `*-off`. +When also using the main target, keep the main target before the optional ones: + +[.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 +.... +==== |