summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorAvatar Ciaran McCreesh <ciaran.mccreesh@googlemail.com> 2008-11-03 23:08:55 +0000
committerAvatar Ciaran McCreesh <ciaran.mccreesh@googlemail.com> 2008-11-03 23:08:55 +0000
commitf88f4fb4f57c795400e1c0ad97e61724e524c9bd (patch)
tree06953b63d85de97352d6494d89c999b811cd8438
parent603b45ead739bab760f1af4299e6b04c8106a896 (diff)
downloadexherbo-f88f4fb4f57c795400e1c0ad97e61724e524c9bd.tar.gz
exherbo-f88f4fb4f57c795400e1c0ad97e61724e524c9bd.tar.xz
MYOPTIONS requirements
-rw-r--r--docs/eapi/exheres-for-smarties.txt119
1 files changed, 115 insertions, 4 deletions
diff --git a/docs/eapi/exheres-for-smarties.txt b/docs/eapi/exheres-for-smarties.txt
index 5bb90ce..c7b6c24 100644
--- a/docs/eapi/exheres-for-smarties.txt
+++ b/docs/eapi/exheres-for-smarties.txt
@@ -70,8 +70,8 @@ that the `extglob` shell option is set. The locale is preset to `C`.
- `SUMMARY` (short, like `DESCRIPTION` is in 0-based EAPIs)
- `DESCRIPTION` (long, optional)
- `PLATFORMS` (like `KEYWORDS`)
-- `MYOPTIONS` (like `IUSE`, but must include `SUBOPTIONS` things)
- `DEPENDENCIES` (see below)
+- `MYOPTIONS` (like `IUSE`, but much more useful, see below)
- `BUGS_TO` (see below)
- `REMOTE_IDS` (see below)
- `UPSTREAM_CHANGELOG`, `UPSTREAM_RELEASE_NOTES`, `UPSTREAM_DOCUMENTATION` (see below)
@@ -280,8 +280,7 @@ Annotation keys we recognise currently are:
(only use if you really really have to, and most definitely not just for collisions).
- `upgrade-blocked-before` would suggest upgrading the blocked package before we are merged
-Annotations are not, in principle, limited to package and block dep specs. You can put them after
-other things too:
+Annotations are not limited to package and block dep specs. You can put them after other things too:
DEPENDENCIES="
build,run: [[ here = [ would apply to the labels ] ]]
@@ -297,12 +296,124 @@ other things too:
mirror://foo/${PNV}.tar.bz2 [[ here = [ would apply to the URI ] ]]
"
-but we don't do anything with any of those keys.
+but we only use those for `MYOPTIONS` currently.
Don't overdo annotations. Blockers almost always benefit from having them. So do suggestions. Normal
deps, not so much, although sometimes a little `[[ note = [ configure.ac says 2.0, but we get runtime
terminal corruption unless we use at least 2.3 ] ]]` might not go amiss.
+### MYOPTIONS
+
+`MYOPTIONS` is a bit like `IUSE`, except more powerful. *All* flags have to be listed in
+`MYOPTIONS`, even `SUBOPTIONS` flags, and there is no special `ARCH` handling. Labels are used to
+select the active suboption. For example:
+
+ MYOPTIONS="
+ foo
+ bar
+ baz
+ linguas:
+ en
+ fr
+ platforms:
+ x86
+ "
+
+You need to list any platforms that will be used in dependencies or queried in any way; there is no
+need to list a platform simply because a package is keyworded on that platform.
+
+Local flag descriptions, and more detailed descriptions for flags with a global meaning, are
+specified via annotations:
+
+ MYOPTIONS="
+ imlib2 [[ description = [ Use imlib2 to render icons ] ]]
+ "
+
+Do *not* start your description with "enables support for". This is superfluous. Do not describe
+`foo` as "Support for foo" unless even Wulf's dead grandmother knows what foo is; you can at least
+manage "Support for the foo image format".
+
+Flags can also have requirements:
+
+ MYOPTIONS="
+ foo
+ bar
+ baz [[ requires = [ foo -bar ] ]]
+ linguas:
+ en
+ en_GB [[ requires = [ linguas: en ] ]]
+ "
+
+These are checked just before `pkg_pretend` is called (and even if they fail, `pkg_pretend` will
+still be called). Theoretically you can override `pkg_bad_options` (being sure to call `default` to
+get the standard description displayed) to get improved error messages, but this may not be a good
+idea.
+
+The `requires` annotation can be applied to an all-of block. This is a shortcut for applying the
+requirement to each child (this is special behaviour -- annotations do not usually get applied to
+children when on a block):
+
+ MYOPTIONS="
+ X
+ python
+ (
+ gtk [[ requires = python ]]
+ qt
+ motif
+ ) [[ requires = X ]]
+ "
+
+Here, `gtk` requires both `X` and `python` (but we discourage this style -- see below).
+
+All-of blocks also support a `number-selected` annotation, which can have the value `at-least-one`,
+`at-most-one` or `exactly-one`:
+
+ MYOPTIONS="
+ X
+ python
+ (
+ gtk [[ requires = python ]]
+ qt
+ motif
+ ) [[
+ number-selected = at-most-one
+ requires = X
+ ]]
+ "
+
+This can be done conditionally. Make sure you apply the annotations to an all-of block, *not* the
+conditional block. Any requirements inside a conditional block are tested only if the condition is
+met; any flags listed inside a conditional block are *always* considered part of `MYOPTIONS`, but
+the conditional flag itself must be explicitly listed beforehand.
+
+ MYOPTIONS="
+ X
+ python
+ (
+ gtk [[ requires = python ]]
+ qt
+ motif
+ ) [[ requires = X ]]
+ X? ( ( gtk qt motif ) [[ number-selected = exactly-one ]]
+ "
+
+Negative flags are allowed, both as a `requires` value and inside an all-of block. Use sparingly.
+
+In terms of style, it's clearest to list all relevant flags first, along with any descriptions, and
+then go through and apply any requirements, avoiding grouping requirements together. So:
+
+ MYOPTIONS="
+ X [[ description = [ Build a graphical user interface ] ]]
+ python [[ description = [ Generate bindings for the Python programming language ] ]]
+ gtk
+ qt
+ motif
+
+ gtk [[ requires = python ]]
+ ( gtk qt motif ) [[ requires = X ]]
+ X? ( ( gtk qt motif ) [[ number-selected = exactly-one ]] )
+ "
+
### BUGS\_TO
Currently `BUGS_TO` should look like this: