trivial: initialise $CYAN in griddle

Signed-off-by: G. Branden Robinson <Branden.Robinson@data61.csiro.au>

convert license headers to SPDX

Includes license review of 3rd-party files, adding missing upstream
headers, and moving the UNSW OZPLB license into its own file rather
than replicating it in the header.

trivial: fix bug number and comment in griddle

trivial: fix paste error in URL

griddle: Use bash and explain why.

This script uses bash for its execution, but not because it uses any
Bashisms; instead, it is to work around a POSIX-violating bug in signal
handling in dash, which is the /bin/sh on most Debian-based systems.
See <https://bugs.debian.org/bug=683671>, filed in 2012 and still not
fixed (posh has the same problem; ksh, mksh, yash, and zsh do not).

WIP: improve signal handler

...to serve as a better model for any other shell trap handling we end
up doing.

griddle: adapt to cmake toolchain autodetection

Work around recent changes in our CMake scripts' toolchain
autodetection. When calling `cmake` to run our custom platform-listing
script, set CMAKE_TOOLCHAIN_FILE to something it will ignore.

Thanks to Kent for the advice.

Also fix bad indentation and use a named rather than a positional
variable reference when they are synonymous.

griddle: dequote $CMAKE_ARGS

Dequote variable dereference for the same reason we do in the main
execution path. Add comment.

Thanks to Kent for noting the problem.

griddle: fix lettercase of variable name

Avoid dereferencing an undefined variable.

griddle: Add mark_as_advanced command to parser

griddle can parse mark_as_advanced commands in easy_settings.cmake by
ignoring them. This allows internal configuration options to be exposed
to easier configuration by using mark_as_advanced to clear their
advanced status.

griddle: Support using project repo as source dir

If there isn't a top level CMakeLists.txt, but an easy-settings.cmake
was found, then use the real directory of easy-settings.cmake as the
source directory to initialise CMake from.

griddle: Re-run cmake in build directory

Once a build is initialised, re-running CMake can be given either the
source or build directory to rerun. Rerunning in the build dir is more
defensive against potentially different source directories.

griddle: bring platform help "in-house"

SELFOUR-2337. Using `--PLATFORM=help` to provoke CMake into issuing a
diagnostic reporting all the valid platform identifier strings did not
work in an already-configured tree. Implement the search for valid
platform identifiers ourselves, and expose a new option,
`--platform-help`, to report them. As a nice side effect, requesting
platform help no longer makes `griddle` exit with a nonzero status.

* cmake-tool/griddle:
+ Add new function, `show_platform_help()`, that uses a snippet of
CMake script courtesy of Kent McLeod.
+ In comment, reference JIRA in which the better, CMake-based fix for
the project-specific platform support is being tracked.
+ Emit diagnostic regarding project/platform support.
+ Add new option, `--platform-help`.
+ Document new option.
+ Remove old code which contrived to get CMake to report the platform
identifiers.

Revert "griddle: bring platform help "in-house""

Clean up since I forgot to rebase/squash before merging.

This reverts commit 0837fc6e2610b86f43c1f048ab1a4d196f625409.

Revert "squash: more improvements"

Clean up since I forgot to rebase/squash before merging.

This reverts commit e63e15cea2d9860009581f20b49e92c0de080101.

Revert "squash: add alternative show_platform_help()"

Clean up since I forgot to rebase/squash before merging.

This reverts commit 8e14dfc42b6e070b8975dc94cc14f4bdfd05b32b.

Revert "squash: clarify comment"

Clean up since I forgot to rebase/squash before merging.

This reverts commit 7c8550e8fc1ac02e90e13ad08d9e25421a6e695b.

Revert "squash: add diagnostic regarding project/platform support"

Clean up since I forgot to rebase/squash before merging.

This reverts commit f488f6f7cf91c1bc8cf37672848f4f72686d056b.

Revert "squash: choose a platform help strategy"

Clean up since I forgot to rebase/squash before merging.

This reverts commit 2925818e7c2ba30bb8742834c2c8c5024efe1caa.

squash: choose a platform help strategy

Add comment referencing JIRA in which the better, CMake-based fix for
the project-specific platform support is being tracked.

Remove show_platform_help_old() and extend_diagnostic() functions, since
the former was the only user of the latter.

squash: add diagnostic regarding project/platform support

squash: clarify comment

...so people don't mistake `message()` for a shell function.

squash: add alternative show_platform_help()

Here's an alternative `show_platform_help()` that uses a snippet of
CMake script courtesy of Kent McLeod.

Reviewers: please compare it with `show_platform_help_old()` and express
your preference, if any. I think both are a little ugly, but in
differnt ways. I have a slight preference for this new version, because
it keeps me out of the business of parsing cmake. It also makes a
useful exhibit of why I never, ever use temporary files if I can help
it. The problems they create arise from the Unix environment, not the
shell language.

I will delete the unused implementation before merging.

squash: more improvements

Try to prevent a recurrence of the exynos5 problem. Warn about any
"declare_platform()" lines that suffered violence at the hands of the
styler.

Add new extend_diagnostic() function to support multi-line diagnostic
messages.

Remove "--recursive" flag from grep call, useless in this context.

griddle: bring platform help "in-house"

SELFOUR-2337. Using `--PLATFORM=help` to provoke CMake into issuing a
diagnostic reporting all the valid platform identifier strings did not
work in an already-configured tree. Implement the search for valid
platform identifiers ourselves, and expose a new option,
`--platform-help`, to report them. As a nice side effect, requesting
platform help no longer makes `griddle` exit with a nonzero status.

* cmake-tool/griddle:
+ Add new function, `show_platform_usage()`.
+ Add new option, `--platform-help`.
+ Document new option.
+ Remove old code which contrived to get CMake to report the platform
identifiers.

griddle: fix quoting issue

Found a dusty corner of shell syntax, which was exposed by attempting:
`griddle --PLATFORM=sabre --SIMULATION=ON`
instead of:
`griddle --SIMULATION=ON --PLATFORM=sabre`

Change quoting style so that an embedded space (which still appears to
be word-separated to the shell) is not passed to `cmake`. (For those
wanting to test their shell mastery, the problem here was _not_ the
double-quotes in the now-removed version of the assignment to
`CMAKE_ARGS`.)

Delete a stale comment.

Update comment about unquoted arguments to `cmake`.

griddle: tweak configuration stability diagnostics

Now that the big CMake file refactor means only one CMake pass is
necessary, it's noisy for `griddle` to push a colorful "all is well"
diagnostic to the terminal before exiting.

However, if you re-run `griddle` in a dirty build directory with
different parameters, multiple `cmake` runs may still be necessary. So
keep the logic, but only emit the "now stable" diagnostic if we
previously emitted a "configuration unstable" one.

CMake: Require -C settings.cmake for apps

This supports the new build structure where instead of blindly including
every settings.cmake file in every projects/ folder we can find, we
instead require a single settings.cmake file in the top level directory.

griddle: add support for tx1 and tx2

Build-tested on tx1 and tx2, neither of which yet support simulation.

griddle: accept unset $EXTRA_ARGS

We don't always need the extra arguments, so don't abort (due to set -u)
if they aren't set.

Build-tested on:
* x86_64
* x86_64 with simulation
* sabre
* sabre with simulation
* tk1 (which does not support simulation)

griddle: behave better on dumb terminals

`tput` exits with a nonzero status if a string capability is unsupported
by the _terminal_, not unrecognized by the terminfo database.
Consequently, the script would exit (thanks to `set -e`) when querying
the `bold` and `sgr0` capabilities on the paradigmatic dumb terminal
(TERM=dumb). Handle this case.

griddle: validate all arguments before exiting

Throw the user more than one bone at a time by validating all
command-line options, then tell them how to get help after reporting all
such problems (if any).

Also tweak variable names and add comments for clarity (I hope).

griddle: remove CMake cache backup file when done

After we're satisfied that the current cache file is a duplicate of the
backup, remove it.

Also, observe the DRY maxim and pull the name of the cache backup file
into a variable.

griddle: add hack to let sabre and tx1 build

While we are waiting on the single-passification of all CMakeLists
(which will also solve the "configuration stability" problem mentioned
in this script), synthesize cmake flags for sabre and tx1 so griddle can
actually be used on those platforms.

Thanks to Simon Shields for trying out griddle, prompting this necessary
improvement, and testing the fix on a tx1 board.

Tested on x86_64 and sabre (simulated) and tx1 (real).

griddle: fix problems uncovered by testing

* Handle boolean flags correctly. (!)
* Abort if cmake fails.
* Fix missing $ sigil when dereferencing variable in diagnostic message.
* Convert fatal error to regular error in function and return failure
status. This way the caller can decide what to do.
* More carefully distinguish between $ARG and $FLAG. (The distinction
is semantic only, but helps when reading the script.)
* When looping through arguments, reset variables set by previous
iterations (in POSIX shell, there is no truly local scope).
* All configuration variables take values (we are more strict than the C
preprocessor), so report an error when the user specifies a
configuration flag without a value.
* Dequote flags to cmake (see comment for rationale).
* Dequote dereference of variable with a known-sane value.
* Add comments.

Tested with sel4test on x86_64 (simulated), sabre (simulated), and tx1
(real hardware, courtesy of Simon Shields).

griddle: reassure user about config stability

The former diagnostic could have left the impression that the
configuration instability was an unrectified problem. Instead, mention
what we're doing about it and announce resolution.

griddle: add "notice" diagnostic level

Add function for displaying notice diagnostics. Steal the color green
from debug diagnostics for notices, and relegate debug messages to using
cyan.

griddle: Re-run cmake as much as necessary

...and warn about it when the cache file changes from run to run.

Add warning diagnostic level to support the corresponding message, as it
is an infelicity rather than a failure.

I'm a little unclear on the details, but apparently the x86 SMP build
for sel4bench needed _four_ cmake runs to stabilise the configuration,
not three.

Kent is working on the underlying insanity, but in the meantime, we
throw away init-build.sh's heuristic of "three times should be enough"
and keep kicking cmake until it reaches an equilibrium position.

Even after that is resolved, we'll still be running cmake one more time
than should be necessary (meaning: twice instead of once), but this way
the extra run will serve as a regression test. (We could also then dial
the severity of this problem up to "fatal", if we like.)

Pass crafted cmake args to cmake, not all of them

We went to the trouble of munging them into shape; actually pass the
right ones.

griddle: cope when easy settings are the empty set

Handle the case when we find no configuration variables in the
easy-settings.cmake file. show_usage() already dealt with this but our
call to getopt did not.

griddle: exit (nonzero) when throwing usage error

When handling an unrecognized option from getopt, we weren't actually
exiting after showing the usage message. Do so instead of bulling
ahead.

Run CMake with init flags if there's no cache

* If the CMake cache file does not exist or if the --compiler flag was
given, call CMake with initialisation flags.
* Pull the path to the toolchain into a variable; we might be relocating
it soon.
+ Reorder CMake compiler-related variables to reflect dependencies.

Add "griddle" tool to enable easy build scenarios