Excluding builds¶
cmany accepts arguments for excluding certain combinations of build items. These arguments specify combination exclusion rules which apply either to a build’s name or to the individual build items of which the build is composed.
When multiple combination arguments are given, they are processed in the order in which they are given. A build is then included if it successfully matches every argument.
Be aware that for added convenience, cmany offers the commands
show_build_names
and show_builds
, which are useful for testing the
input arguments.
Excluding builds by item name¶
To exclude a build based on its composing items, cmany offers the following arguments, which should be fairly self-explaining:
- systems (
-s/--systems
): -xs/--exclude-systems sys1[,sys2[,...]]
-is/--include-systems sys1[,sys2[,...]]
- systems (
- architectures (
-a/--architectures
): -xa/--exclude-architectures arch1[,arch2[,...]]
-ia/--include-architectures arch1[,arch2[,...]]
- architectures (
- compilers (
-c/--compilers
): -xc/--exclude-compilers comp1[,comp2[,...]]
-ic/--include-compilers comp1[,comp2[,...]]
- compilers (
- build types (
-t/--build-types
): -xt/--exclude-build-types btype1[,btype2[,...]]
-it/--include-build-types btype1[,btype2[,...]]
- build types (
- variants (
-v/--variants
): -xv/--exclude-variants var1[,var2[,...]]
-iv/--include-variants var1[,var2[,...]]
- variants (
Each argument receives a comma-separated list of item names. These names are matched literally to the name of any item of the same type, and the prospective build (which would combine those items) is included or excluding according to the rule.
Also note the mnemonic for the build item arguments: the letter you use to specify a build item is the letter after the short form of the include or exclude flag.
Excluding builds by build name¶
These are the arguments to prevent a build by matching against the build’s final name:
-xb/--exclude-builds rule1[,rule2[,...]]
: excludes a build if its name matches any of the rules-ib/--include-builds rule1[,rule2[,...]]
: includes a build only if its name matches any of the rules-xba/--exclude-builds-all rule1[,rule2[,...]]
: excludes a build if its name matches all of the rules-iba/--include-builds-all rule1[,rule2[,...]]
: includes a build only if its name matches all of the rules
As noted above, each argument accepts a comma-separated list of Python
regular expressions that will
be used as matching rules to each build name. A build is included only if its
name successfully matches every combination argument. Note that the form of a
build’s name is
{system}-{architecture}-{compiler}-{build_type}[-{variant}]
. Note also
the presence of the hyphen separating the build items; it can be used to
distinguish between similarly named items such as x86
and x86_64
.
The rules do not need to be regular expressions: passing the full names of the builds to the argument works as expected.
Examples¶
As a first example, consider this command which addresses 12 builds by combining 2 architectures, 2 build types and 3 variants:
$ cmany show_build_names -a x86,x86_64 -t Debug,Release \
-v none,'foo: -D FOO','bar: -D BAR'
linux-x86-g++5.4-Debug
linux-x86-g++5.4-Debug-foo
linux-x86-g++5.4-Debug-bar
linux-x86-g++5.4-Release
linux-x86-g++5.4-Release-foo
linux-x86-g++5.4-Release-bar
linux-x86_64-g++5.4-Debug
linux-x86_64-g++5.4-Debug-foo
linux-x86_64-g++5.4-Debug-bar
linux-x86_64-g++5.4-Release
linux-x86_64-g++5.4-Release-foo
linux-x86_64-g++5.4-Release-bar
Now, if we want to exclude foo
variants of the x86
architecture, we
can use:
$ cmany show_build_names -a x86,x86_64 -t Debug,Release \
-v none,'foo: -D FOO','bar: -D BAR' \
--exclude-builds '.*x86-.*foo'
linux-x86-g++5.4-Debug
linux-x86-g++5.4-Debug-bar # NOTE: no x86 foo variant
linux-x86-g++5.4-Release
linux-x86-g++5.4-Release-bar # NOTE: no x86 foo variant
linux-x86_64-g++5.4-Debug
linux-x86_64-g++5.4-Debug-foo
linux-x86_64-g++5.4-Debug-bar
linux-x86_64-g++5.4-Release
linux-x86_64-g++5.4-Release-foo
linux-x86_64-g++5.4-Release-bar
Note the hyphen appearing in the regular expression passed to
--exclude-builds '.*x86-.*foo'
. This prevents it from matching
x86_64
. As noted above, the name of the build is obtained by separating
the build items of which it is composed with an hyphen. If this regular
expression did not have the hyphen and was instead .*x86.*foo
, then it
would match both x86
and x86_64
, with the result that no builds would
contain the foo
variant.
For the previous example, it is actually easier to have the foo
variant
directly exclude the x86
architecture. The result is exactly the same:
$ cmany show_builds -a x86,x86_64 -t Debug,Release \
-v none,'foo: -D FOO -xa x86','bar: -D BAR'
You could instead have the x86
architecture exclude the foo
variant,
with the same result:
$ cmany show_builds -a 'x86: -xv foo',x86_64 -t Debug,Release \
-v none,'foo: -D FOO','bar: -D BAR' \
The logical opposite of --exclude-builds
is naturally
--include-builds
:
$ cmany show_builds -a x86,x86_64 -t Debug,Release \
-v none,'foo: -D FOO','bar: -D BAR' \
--include-builds '.*x86-.*foo'
linux-x86-g++5.4-Debug-foo
linux-x86-g++5.4-Release-foo
This can also be done with the following command:
$ cmany show_builds -a x86,x86_64 -t Debug,Release \
-v none,'foo: -D FOO','bar: -D BAR' \
-ia x86 -iv foo
If you are wondering about the usefulness of the -i*/--include
arguments,
consider that the compile-edit loop is usually repeated many times. Being
that the arguments to cmany usually come to a certain degree of complexity
(something which Project mode also addresses),
rewriting them every time is something we would like to avoid. So when you
want to narrow down your previous command (or your project setup) just to a
certain combination of builds, the --include-*
arguments usually come in
very handy.
Like all the arguments above, item combination arguments can be used both at the cmany command level or at each build item level.
You may have noticed that it does not make much sense to provide the
--include-*
arguments in a build item specification, as combination is
implied for every build item. However, being able to use these at the scope
of the command is certainly useful, either as a form of saving extensive
editing when reusing complicated cmany commands (for example in shell
sessions), or with Project mode.