From owner-svn-doc-all@FreeBSD.ORG Tue May 29 18:07:56 2012 Return-Path: Delivered-To: svn-doc-all@freebsd.org Received: from mx1.freebsd.org (mx1.freebsd.org [IPv6:2001:4f8:fff6::34]) by hub.freebsd.org (Postfix) with ESMTP id BA04E1065670; Tue, 29 May 2012 18:07:56 +0000 (UTC) (envelope-from crees@FreeBSD.org) Received: from svn.freebsd.org (svn.freebsd.org [IPv6:2001:4f8:fff6::2c]) by mx1.freebsd.org (Postfix) with ESMTP id A3A7C8FC1A; Tue, 29 May 2012 18:07:56 +0000 (UTC) Received: from svn.freebsd.org (localhost [127.0.0.1]) by svn.freebsd.org (8.14.4/8.14.4) with ESMTP id q4TI7uQq094272; Tue, 29 May 2012 18:07:56 GMT (envelope-from crees@svn.freebsd.org) Received: (from crees@localhost) by svn.freebsd.org (8.14.4/8.14.4/Submit) id q4TI7uba094270; Tue, 29 May 2012 18:07:56 GMT (envelope-from crees@svn.freebsd.org) Message-Id: <201205291807.q4TI7uba094270@svn.freebsd.org> From: Chris Rees Date: Tue, 29 May 2012 18:07:56 +0000 (UTC) To: doc-committers@freebsd.org, svn-doc-all@freebsd.org, svn-doc-head@freebsd.org X-SVN-Group: doc-head MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Cc: Subject: svn commit: r38931 - head/en_US.ISO8859-1/books/porters-handbook X-BeenThere: svn-doc-all@freebsd.org X-Mailman-Version: 2.1.5 Precedence: list List-Id: "SVN commit messages for the entire doc trees \(except for " user" , " projects" , and " translations" \)" List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Tue, 29 May 2012 18:07:56 -0000 Author: crees (ports committer) Date: Tue May 29 18:07:56 2012 New Revision: 38931 URL: http://svn.freebsd.org/changeset/doc/38931 Log: Document new OPTIONS framework Reviewed by: wblock Modified: head/en_US.ISO8859-1/books/porters-handbook/book.sgml Modified: head/en_US.ISO8859-1/books/porters-handbook/book.sgml ============================================================================== --- head/en_US.ISO8859-1/books/porters-handbook/book.sgml Tue May 29 15:07:17 2012 (r38930) +++ head/en_US.ISO8859-1/books/porters-handbook/book.sgml Tue May 29 18:07:56 2012 (r38931) @@ -3663,19 +3663,17 @@ ALWAYS_KEEP_DISTFILES= yes <makevar>USE_<replaceable>*</replaceable></makevar> - A number of variables exist in order to encapsulate - common dependencies that many ports have. Although their - use is optional, they can help to reduce the verbosity of + Several variables exist to define + common dependencies shared by many ports. Their + use is optional, but helps to reduce the verbosity of the port Makefiles. Each of them is styled as - USE_*. The - usage of these variables is restricted to the port + USE_*. + These variables may be used only in the port Makefiles and - ports/Mk/bsd.*.mk and is not designed - to encapsulate user-settable options — use - WITH_* and - WITHOUT_* for - that purpose. + ports/Mk/bsd.*.mk. They are not meant + for user-settable options — use + PORT_OPTIONS for that purpose. It is always incorrect to set any @@ -3880,11 +3878,12 @@ LIB_DEPENDS= bar:${PORTSDIR}/foo/bar Correct Declaration of an Optional Dependency - OPTIONS= BAR "Enable bar support" off + OPTIONS_DEFINE= BAR +BAR_DESC= Enable bar support -.include <bsd.port.pre.mk> +.include <bsd.port.options.mk> -.if defined(WITH_BAR) && !defined(WITHOUT_BAR) +.if ${PORTOPTIONS:MBAR} LIB_DEPENDS= bar:${PORTSDIR}/foo/bar .endif @@ -4089,15 +4088,14 @@ ${MANPREFIX}/man/de/man3/baz.3.gz Makefile Options - Some large applications can be built in a number of - configurations, adding functionality if one of a number of - libraries or applications is available. Examples include + Many applications can be built with optional or differing + configurations. Examples include choice of natural (human) language, GUI versus command-line, - or type of database to support. Since not all users want - those libraries or applications, the ports system provides - hooks that the port author can use to control which - configuration should be built. Supporting these properly will - make users happy, and effectively provide 2 or more ports for + or type of database to support. Users may need a different + configuration than the default, so the ports system provides + hooks the port author can use to control which variation + will be built. Supporting these options properly will + make users happy, and effectively provide two or more ports for the price of one. @@ -4109,7 +4107,7 @@ ${MANPREFIX}/man/de/man3/baz.3.gzWITHOUT_* These variables are designed to be set by the system - administrator. There are many that are standardized in + administrator. There are many that are standardized in the ports/KNOBS file. @@ -4131,7 +4129,7 @@ ${MANPREFIX}/man/de/man3/baz.3.gz Unless otherwise specified, these variables are only tested for being set or not set, rather than being set - to some kind of variable such as YES + to a specific value such as YES or NO. @@ -4173,11 +4171,11 @@ ${MANPREFIX}/man/de/man3/baz.3.gz WITHOUT_X11 - If the port can be built both with and - without X support, then it should normally be + Ports that can be built both with and + without X support are normally built with X support. If this variable is defined, then the version that does not have X - support should be built instead. + support will be built instead. @@ -4187,7 +4185,7 @@ ${MANPREFIX}/man/de/man3/baz.3.gz Knob Naming - It is recommended that porters use like-named knobs, + Porters should use like-named knobs, both for the benefit of end-users and to help keep the number of knob names down. A list of popular knob names can be found in the Background - The OPTIONS variable gives the user - who installs the port a dialog with the available options - and saves them to - /var/db/ports/portname/options. - Next time when the port has to be rebuild, the options are - reused. Never again you will have to remember all the - twenty - WITH_* and - WITHOUT_* - options you used to build this port! + The OPTIONS_* variables give the user + installing the port a dialog showing the available options, + and then saves those options to + /var/db/ports/${UNIQUENAME}/options. + The next time the port is built, the options are + reused. When the user runs make config (or runs make build for the first time), - the framework will check for - /var/db/ports/portname/options. - If that file does not exist, it will use the values of - OPTIONS to create a dialog box where + the framework checks for + /var/db/ports/${UNIQUENAME}/options. + If that file does not exist, the values of + OPTIONS_* are used, and a dialog box is displayed where the options can be enabled or disabled. Then the options file is saved and the - selected variables will be used when building the + configured variables are used when building the port. If a new version of the port adds new OPTIONS, the dialog will be presented - to the user, with the saved values of old + to the user with the saved values of old OPTIONS prefilled. - Use make showconfig to see the + make showconfig shows the saved configuration. Use make rmconfig to remove the saved configuration. @@ -4242,50 +4236,141 @@ ${MANPREFIX}/man/de/man3/baz.3.gz Syntax - The syntax for the OPTIONS variable - is: - - OPTIONS= OPTION "descriptive text" default ... + OPTIONS_DEFINE contains a list of + OPTIONS to be used. These are independent + of each other and are not grouped: + + OPTIONS_DEFINE= OPT1 OPT2 + + Once defined, OPTIONS are + described (optional, but strongly recommended): + + OPT1_DESC= Describe OPT1 +OPT2_DESC= Describe OPT2 +OPT3_DESC= Describe OPT3 +OPT4_DESC= Describe OPT4 +OPT5_DESC= Describe OPT5 +OPT6_DESC= Describe OPT6 + + + ports/Mk/bsd.options.desc.mk + has descriptions for many common + OPTIONS; there is usually no need + to override these. + + + + When describing options, view it from the + perspective of the user: What does it do? + and Why would I want to enable this? Do + not just repeat the name. For example, describing the + NLS option as + include NLS support does not help the + user who can already see the option name but may not + + know what it means. Describing it as Native + Language Support via gettext utilities is + much more helpful. + + + OPTIONS can be grouped as radio + choices, where only one choice from each group is + allowed: + + OPTIONS_SINGLE= SG1 +OPTIONS_SINGLE_SG1= OPT3 OPT4 + + OPTIONS can also be grouped as + multiple-choice lists, where + at least one option must be + enabled: + + OPTIONS_MULTI= MG1 +OPTIONS_MULTI_MG1= OPT5 OPT6 + + OPTIONS are unset by default, + unless they are listed in + OPTIONS_DEFAULT: - The value for default is either ON - or OFF. Multiple repetitions of these - three fields are allowed. + OPTIONS_DEFAULT= OPT1 OPT3 OPT6 - OPTIONS definition must appear + OPTIONS definitions must appear before the inclusion of bsd.port.options.mk. The - WITH_* and WITHOUT_* - variables can only be tested after the inclusion of + PORT_OPTIONS variable can only be + tested after the inclusion of bsd.port.options.mk. Inclusion of bsd.port.pre.mk can be used instead, too, and is still widely used in ports written before the introduction of bsd.port.options.mk. But be aware that some variables will not work as expected after the inclusion of - bsd.port.pre.mk, typically + bsd.port.pre.mk, typically some USE_* flags. Simple Use of <makevar>OPTIONS</makevar> - OPTIONS= FOO "Enable option foo" On \ - BAR "Support feature bar" Off + OPTIONS_DEFINE= FOO BAR +FOO_DESC= Enable option foo +BAR_DESC= Support feature bar + +OPTIONS_DEFAULT=FOO .include <bsd.port.options.mk> -.if defined(WITHOUT_FOO) -CONFIGURE_ARGS+= --without-foo +.if ${PORT_OPTIONS:MFOO} +CONFIGURE_ARGS+=--without-foo .else -CONFIGURE_ARGS+= --with-foo +CONFIGURE_ARGS+=--with-foo .endif -.if defined(WITH_BAR) +.if ${PORT_OPTIONS:MBAR} RUN_DEPENDS+= bar:${PORTSDIR}/bar/bar .endif .include <bsd.port.mk> + + Practical Use of <makevar>OPTIONS</makevar> + + OPTIONS_DEFINE= EXAMPLES + +OPTIONS_SINGLE= BACKEND +OPTIONS_SINGLE_BACKEND= MYSQL PGSQL BDB + +OPTIONS_MULTI= AUTH +OPTIONS_MULTI_AUTH= LDAP PAM SSL + +EXAMPLES_DESC= Install extra examples +MYSQL_DESC= Use MySQL as backend +PGSQL_DESC= Use PostgreSQL as backend +BDB_DESC= Use Berkeley DB as backend +LDAP_DESC= Build with LDAP authentication support +PAM_DESC= Build with PAM support +SSL_DESC= Build with OpenSSL support + +OPTIONS_DEFAULT= PGSQL LDAP SSL + +.include <bsd.port.options.mk> + +.if ${PORT_OPTIONS:MPGSQL} +USE_PGSQL= yes +CONFIGURE_ARGS+= --with-postgres +.else +CONFIGURE_ARGS+= --without-postgres +.endif + +.if ${PORT_OPTIONS:MICU} +LIB_DEPENDS+= icuuc:${PORTSDIR}/devel/icu +.endif + +# Check other OPTIONS + +.include <bsd.port.mk> + + Old-Style Use of <makevar>OPTIONS</makevar> @@ -4301,6 +4386,12 @@ CONFIGURE_ARGS+= --with-foo .include <bsd.port.post.mk> + + + This method of using OPTIONS + is deprecated, and will be removed at some point. + Do not use this method for new ports. + @@ -4317,7 +4408,7 @@ CONFIGURE_ARGS+= --with-foo Wrong Handling of an Option - .if defined(WITH_FOO) + .if ${PORT_OPTIONS:MFOO} LIB_DEPENDS+= foo.0:${PORTSDIR}/devel/foo CONFIGURE_ARGS+= --enable-foo .endif @@ -4336,7 +4427,7 @@ CONFIGURE_ARGS+= --enable-foo Correct Handling of an Option - .if defined(WITH_FOO) + .if ${PORT_OPTIONS:MFOO} LIB_DEPENDS+= foo.0:${PORTSDIR}/devel/foo CONFIGURE_ARGS+= --enable-foo .else @@ -7987,7 +8078,7 @@ WX_COMPS= wx contrib .include <bsd.port.pre.mk> -.if defined(WITH_WX) || ${HAVE_WX:Mwx-2.4} != "" +.if defined(WITH_WX) || !empty(PORT_OPTIONS:MWX) || !empty(HAVE_WX:Mwx-2.4) USE_WX= 2.4 CONFIGURE_ARGS+= --enable-wx .endif @@ -8004,7 +8095,7 @@ WANT_WX= 2.6 .include <bsd.port.pre.mk> -.if defined(WITH_WXPYTHON) || ${HAVE_WX:Mpython} != "" +.if defined(WITH_WXPYTHON) || !empty(PORT_OPTIONS:MWXPYTHON) || !empty(HAVE_WX:Mpython) WX_COMPS+= python CONFIGURE_ARGS+= --enable-wxpython .endif @@ -8495,7 +8586,7 @@ LUA_COMPS= lua ruby .include <bsd.port.pre.mk> -.if defined(WITH_LUA5) || ${HAVE_LUA:Mlua-5.[01]} != "" +.if defined(WITH_LUA5) || !empty(PORT_OPTIONS:MLUA5) || !empty(HAVE_LUA:Mlua-5.[01]) USE_LUA= 5.0-5.1 CONFIGURE_ARGS+= --enable-lua5 .endif @@ -8512,7 +8603,7 @@ WANT_LUA= 4.0 .include <bsd.port.pre.mk> -.if defined(WITH_TOLUA) || ${HAVE_LUA:Mtolua} != "" +.if defined(WITH_TOLUA) || !empty(PORT_OPTIONS:MTOLUA) || !empty(HAVE_LUA:Mtolua) LUA_COMPS+= tolua CONFIGURE_ARGS+= --enable-tolua .endif