From owner-svn-ports-all@freebsd.org Wed Jul 3 07:31:02 2019 Return-Path: Delivered-To: svn-ports-all@mailman.ysv.freebsd.org Received: from mx1.freebsd.org (mx1.freebsd.org [IPv6:2610:1c1:1:606c::19:1]) by mailman.ysv.freebsd.org (Postfix) with ESMTP id 8801C15CA020; Wed, 3 Jul 2019 07:31:02 +0000 (UTC) (envelope-from koobs@FreeBSD.org) Received: from mxrelay.nyi.freebsd.org (mxrelay.nyi.freebsd.org [IPv6:2610:1c1:1:606c::19:3]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) server-signature RSA-PSS (4096 bits) client-signature RSA-PSS (4096 bits) client-digest SHA256) (Client CN "mxrelay.nyi.freebsd.org", Issuer "Let's Encrypt Authority X3" (verified OK)) by mx1.freebsd.org (Postfix) with ESMTPS id 2B2F38D70D; Wed, 3 Jul 2019 07:31:02 +0000 (UTC) (envelope-from koobs@FreeBSD.org) Received: from repo.freebsd.org (repo.freebsd.org [IPv6:2610:1c1:1:6068::e6a:0]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (Client did not present a certificate) by mxrelay.nyi.freebsd.org (Postfix) with ESMTPS id 06D688859; Wed, 3 Jul 2019 07:31:02 +0000 (UTC) (envelope-from koobs@FreeBSD.org) Received: from repo.freebsd.org ([127.0.1.37]) by repo.freebsd.org (8.15.2/8.15.2) with ESMTP id x637V17F082413; Wed, 3 Jul 2019 07:31:01 GMT (envelope-from koobs@FreeBSD.org) Received: (from koobs@localhost) by repo.freebsd.org (8.15.2/8.15.2/Submit) id x637V1Z1082412; Wed, 3 Jul 2019 07:31:01 GMT (envelope-from koobs@FreeBSD.org) Message-Id: <201907030731.x637V1Z1082412@repo.freebsd.org> X-Authentication-Warning: repo.freebsd.org: koobs set sender to koobs@FreeBSD.org using -f From: Kubilay Kocak Date: Wed, 3 Jul 2019 07:31:01 +0000 (UTC) To: ports-committers@freebsd.org, svn-ports-all@freebsd.org, svn-ports-head@freebsd.org Subject: svn commit: r505730 - head/Mk/Uses X-SVN-Group: ports-head X-SVN-Commit-Author: koobs X-SVN-Commit-Paths: head/Mk/Uses X-SVN-Commit-Revision: 505730 X-SVN-Commit-Repository: ports MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit X-Rspamd-Queue-Id: 2B2F38D70D X-Spamd-Bar: -- Authentication-Results: mx1.freebsd.org X-Spamd-Result: default: False [-2.93 / 15.00]; local_wl_from(0.00)[FreeBSD.org]; NEURAL_HAM_MEDIUM(-1.00)[-0.998,0]; NEURAL_HAM_SHORT(-0.93)[-0.932,0]; ASN(0.00)[asn:11403, ipnet:2610:1c1:1::/48, country:US]; NEURAL_HAM_LONG(-1.00)[-1.000,0] X-BeenThere: svn-ports-all@freebsd.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: SVN commit messages for the ports tree List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Wed, 03 Jul 2019 07:31:02 -0000 Author: koobs Date: Wed Jul 3 07:31:01 2019 New Revision: 505730 URL: https://svnweb.freebsd.org/changeset/ports/505730 Log: Uses/python.mk: Clarify language, messaging and usage for Make it clear that is a declarative not imperative specification to declare what version of Python a port or software *supports*, not the versions it should *use*. The version that gets selected is a function of Python.mk, DEFAULT_VERSIONS which change over time, and can be overridden or otherwise set by the user. While I'm here, add a special note about bare USES=python (without a ), which is likely to be deprecated at some point down the line. In the meantime, describe what the semantics of not specifying a entails, and encourage minimisation of its use where appropriate. Approved by: koobs (python, maintainer) Modified: head/Mk/Uses/python.mk Modified: head/Mk/Uses/python.mk ============================================================================== --- head/Mk/Uses/python.mk Wed Jul 3 07:30:02 2019 (r505729) +++ head/Mk/Uses/python.mk Wed Jul 3 07:31:01 2019 (r505730) @@ -5,33 +5,42 @@ # consumer ports requiring Python at build or run time. # # Feature: python -# Usage: USES=python or USES=python:args -# Valid ARGS: , patch, build, run, test +# Usage: USES=python[:version-spec][,arg,...] +# Valid ARGS: , patch, build, run, test # -# version If your port requires only some set of Python versions, you -# can set this to [min]-[max] or min+ or -max or as an -# explicit version (eg. 3.5-3.6 for [min]-[max], 2.7+ or -3.6 -# for min+ and -max, 2.7 for an explicit version). Example: +# version-spec Declarative specification for the Python version(s) the +# port supports. Subsets and ranges can be specified: # -# USES=python:2.7 # Only use Python 2.7 -# USES=python:3.5+ # Use Python 3.5 or newer -# USES=python:3.5-3.6 # Use Python 3.5 or 3.6 -# USES=python:-3.6 # Use any Python up to 3.6 -# USES=python # Use the set default Python -# # version +# * +# * - +# * + +# * - # -# patch Indicates that Python is needed at patch time and adds -# it to PATCH_DEPENDS. -# build Indicates that Python is needed at build time and adds -# it to BUILD_DEPENDS. -# run Indicates that Python is needed at run time and adds -# it to RUN_DEPENDS. -# test Indicates that Python is needed at test time and adds -# it to TEST_DEPENDS. -# env Indicates that the port does not require a dependency on Python -# itself but needs the environment set up. This is mainly used -# when depending on flavored python ports, or when a correct -# PYTHON_CMD is required. It has the same effect than setting +# Examples: +# +# USES=python:2.7 # Supports Python 2.7 Only +# USES=python:3.5+ # Supports Python 3.5 or later +# USES=python:3.5-3.7 # Supports Python 3.5 to 3.7 +# USES=python:-3.6 # Supports Python up to 3.6 +# USES=python # Supports any/all Python versions +# +# NOTE: should be as specific as possible, matching the versions +# upstream declares support for, without being incorrect. In particular, +# USES=python *without* a means any and all past or future +# versions, including unreleased versions, which is probably incorrect. +# +# Not specifying a should only be used when a more specific +# cannot be specified due to syntax limitations, for +# example: 2.7,3.4-3.6, but even in this case, X.Y+ (2.7+), or -X.Y (-3.6) +# is preferred and likely more correct. +# +# patch Python is needed at patch time. Adds dependency to PATCH_DEPENDS. +# build Python is needed at build time. Adds dependency to BUILD_DEPENDS. +# run Python is needed at run time. Adds dependency to RUN_DEPENDS. +# test Python is needed at test time. Adds dependency to TEST_DEPENDS. +# env Does not depend on Python but needs the environment set up. This +# is mainly used when depending on flavored python ports, or when a +# correct PYTHON_CMD is required. It has the same effect as setting # PYTHON_NO_DEPENDS. # # If build, run and test are omitted, Python will be added as BUILD_DEPENDS,