annotations: do not try to auto-detect JSON format

The script tries to automatically detect the format of the annotations
file (legacy or pure JSON).

However, if the legacy file contains a syntax error, the script will try
to parse the file as JSON (incorrectly) triggering another obscure
error, complaining that the JSON format is invalid.

This hides the capability to detect syntax errors properly in the
annotations file.

To prevent this, introduce a new option --json. In this way the caller
has complete control to decide which format needs to be used to parse
the annotations file.

Signed-off-by: Andrea Righi <andrea.righi@canonical.com>

annotations v0.2

Signed-off-by: Andrea Righi <andrea.righi@canonical.com>

tests: test_override: drop unnecessary debugging print()

Signed-off-by: Andrea Righi <andrea.righi@canonical.com>

tests: add a new unit test to verify the arch override

Signed-off-by: Andrea Righi <andrea.righi@canonical.com>

annotations: properly update arch overrides

New rules that are overriding a whole arch should also override all the
correspondent flavours for that particular arch.

Signed-off-by: Andrea Righi <andrea.righi@canonical.com>

annotations: move sys.dont_write_bytecode to main script

Move sys.dont_write_bytecode to the main script and put a comment that
describe why we need this to be enabled.

Signed-off-by: Andrea Righi <andrea.righi@canonical.com>

annotations: coding style fixes

No functional changes, just some python / shell coding style fixes.

Signed-off-by: Andrea Righi <andrea.righi@canonical.com>

add an 'sanitize' helper script

Add a simple 'sanitize' script that allows to run the "sanitize binary"
from source without installing anything in the system.

Signed-off-by: Andrea Righi <andrea.righi@canonical.com>

pre-commit: add sanity checks

Add pre-commit config to perform sanity checks. It is possible to run
these checks locally via:

 $ pre-commit run --all

Signed-off-by: Andrea Righi <andrea.righi@canonical.com>

annotations: clean up shebang

Get rid of the python shebang where it's not needed.

Signed-off-by: Andrea Righi <andrea.righi@canonical.com>

annotations: properly update configs with included JSON files

Fixes: 6d56aaf ("annotations: support JSON format")
Signed-off-by: Andrea Righi <andrea.righi@canonical.com>

annotations: introduce --no-include

Add an option to skip processing included annotations files. This option
can be useful to convert files from an old format to a newer one, by
dumping the contant of the local leaf-node annotations file, instead of
including the content of external files.

Signed-off-by: Andrea Righi <andrea.righi@canonical.com>

annotations: support JSON format

Allow to read and dump all annotations data in pure JSON format.

With this change applied the "annotations" script is able to read either
the old custom format (format version 4) or a new pure-JSON format
(format version 5).

It is possible to convert an old annotations file to the newer format
simply by running "annotations" (no argument): the script will parse the
old annotations (format version 4) and it will dump in output the new
content in the new pure-JSON format (format version 5).

Signed-off-by: Andrea Righi <andrea.righi@canonical.com>

tests: add an include test case

Signed-off-by: Andrea Righi <andrea.righi@canonical.com>

tests/test_todo_note: drop unnecessary debugging info

Signed-off-by: Andrea Righi <andrea.righi@canonical.com>

add an 'annotations' helper script

Add a simple 'annotations' script that allows to run the main
"annotations binary" from source without installing anything in the
system.

Signed-off-by: Andrea Righi <andrea.righi@canonical.com>

annotations: dump all the structure as JSON if no argument is specified

Signed-off-by: Andrea Righi <andrea.righi@canonical.com>

tests: add tox configuration to automate unit testing

Signed-off-by: Andrea Righi <andrea.righi@canonical.com>

tests: add some basic unit tests

Signed-off-by: Andrea Righi <andrea.righi@canonical.com>

annotations: update: properly update note for arch-flavour configs

Values in the form "arch-flavour" are incorrectly processed in the logic
to determine if the note needs to be updated, causing a bunch of notes
to be incorrectly replaced with 'TODO: update not'.

Fix this by searching the values with the proper arch and flavour.

Signed-off-by: Andrea Righi <andrea.righi@canonical.com>

annotations: update: update note when config is changing

When a new .config is imported some values may change, but the
corresponding note is not always updated to reflect the new value.

This is wrong and it can lead to errors and incorrect information in the
annotations file.

To prevent this from happening automatically add a TODO note when any
config with a note is changing to force the reviewer to update the note.

Signed-off-by: Andrea Righi <andrea.righi@canonical.com>

avoid generating python bytecode

We may want to include these scripts into kernel git repositories, so
better to avoid generating python bytecode to avoid including
unnecessary artifacts.

Signed-off-by: Andrea Righi <andrea.righi@canonical.com>

annotations: make the output of config-check more user-friendly

In case of a config change we shouldn't print an error, but a nicer
message instead explaining that the option simply changed.

Hopefully this will help to avoid all the misunderstanding that usually
happens by priting a normal change as an error.

Signed-off-by: Andrea Righi <andrea.righi@canonical.com>

annotations: make argcomplete optional

Allow to run the main script also when argcomplete is not available.

Signed-off-by: Andrea Righi <andrea.righi@canonical.com>

ci: remove trailing space in pylint.yml

Signed-off-by: Andrea Righi <andrea.righi@canonical.com>

Merge pull request #2 from corytodd/lint-check-prs

ci: run pylint on pull requests

Merge pull request #1 from corytodd/fix-readme--space-delimited

readme: fix header list delimiter

ci: run pylint on pull requests

Add pull_request as a trigger so linting issues are caught before
landing on main.

Signed-off-by: Cory Todd <cory.todd@canonical.com>

readme: fix header list delimiter

The ARCH and FLAVOUR lists are now space delimited.

Signed-off-by: Cory Todd <cory.todd@canonical.com>

doc: update documentation and add README.md

Update documentation with the same information published in the
discourse post [1].

Moreover, convert README.rst into README.md.

[1] https://discourse.ubuntu.com/t/kernel-configuration-in-ubuntu/35857

Signed-off-by: Andrea Righi <andrea.righi@canonical.com>

doc: add LICENSE file

Signed-off-by: Andrea Righi <andrea.righi@canonical.com>

annotations: include sanitize-annotations into kconfig

Signed-off-by: Andrea Righi <andrea.righi@canonical.com>

snap: add snapcraft.yaml

Signed-off-by: Andrea Righi <andrea.righi@canonical.com>

deb: update package description

Signed-off-by: Andrea Righi <andrea.righi@canonical.com>

create pylint.yml for github

Signed-off-by: Andrea Righi <andrea.righi@canonical.com>

integrate coding style checks in setup.py

Signed-off-by: Andrea Righi <andrea.righi@canonical.com>

setup.py: run coding style checks as part of the build

Signed-off-by: Andrea Righi <andrea.righi@canonical.com>

fix pylint warnings

Signed-off-by: Andrea Righi <andrea.righi@canonical.com>

update .gitignore

Signed-off-by: Andrea Righi <andrea.righi@canonical.com>

annotations: add command line autocompletion

Signed-off-by: Andrea Righi <andrea.righi@canonical.com>

packaging: provide debian packaging info

Signed-off-by: Andrea Righi <andrea.righi@canonical.com>

packaging: provide a proper packaging (pip) for the tool

Signed-off-by: Andrea Righi <andrea.righi@canonical.com>

doc: add some refrences to README.rst

Signed-off-by: Andrea Righi <andrea.righi@canonical.com>

doc: rename README.md to README.rst

The README is really an rst file, so rename it properly.

Signed-off-by: Andrea Righi <andrea.righi@canonical.com>

sanitize-annotations: move the script to the top folder

Signed-off-by: Andrea Righi <andrea.righi@canonical.com>

kconfig: fix incompatibility with python < 3.9

Signed-off-by: Andrea Righi <andrea.righi@canonical.com>

move sanitize-annotations into tools/

Signed-off-by: Andrea Righi <andrea.righi@canonical.com>

fix a bunch of pylint warnings

Signed-off-by: Andrea Righi <andrea.righi@canonical.com>

annotations: never drop configs that have notes different than the parent

Signed-off-by: Andrea Righi <andrea.righi@canonical.com>

introduce sanitize-annotations.py

Add a script to (try to) automatically sanitize old annotations files by
dropping all the deprecated flags, arbitrary enforcements rules, etc.

Signed-off-by: Andrea Righi <andrea.righi@canonical.com>

kconfig/annotations.py: support older way of merging dicts

The '|=' update operator for merging dicts is available starting in
python 3.9 however in focal we have python 3.8, which causes the
annotation parsing script to crash.

Support also the old way of merging dicts available since python 3.5
that uses dict unpacking, e.g. dict1 = {**dict1, **dict2}

Signed-off-by: Luke Nowakowski-Krijger <luke.nowakowskikrijger@canonical.com>
Signed-off-by: Andrea Righi <andrea.righi@canonical.com>

annotations: use python3 in the shebang

Make sure to not depend on python-is-python3 and explicitly use python3
for the main script.

Signed-off-by: Andrea Righi <andrea.righi@canonical.com>

annotations: prevent duplicate include lines

Includes are always parsed recursively, but when we save them (e.g.,
when the annotations file is updated) we should always save only the
top-level includes, without repeating the recursive ones.

Signed-off-by: Andrea Righi <andrea.righi@canonical.com>

doc: resync README.md with the one in the main kernel

Signed-off-by: Andrea Righi <andrea.righi@canonical.com>

kconfig: Fix pylint violations

Fix the following:
R0205: Class 'Config' inherits from object, can be safely removed from bases in python3 (useless-object-inheritance)
E1101: Instance of 'Config' has no '_parse' member (no-member)
W0613: Unused argument 'arch' (unused-argument)
W0613: Unused argument 'flavour' (unused-argument)
W1514: Using open without explicitly specifying an encoding (unspecified-encoding)
R0201: Method could be a function (no-self-use)
E1101: Instance of 'Config' has no 'config' member (no-member)
W0707: Consider explicitly re-raising using the 'from' keyword (raise-missing-from)
W0105: String statement has no effect (pointless-string-statement)
W0123: Use of eval (eval-used)
W0102: Dangerous default value [] as argument (dangerous-default-value)
R1723: Unnecessary "elif" after "break" (no-else-break)
R1705: Unnecessary "elif" after "return" (no-else-return)
R1704: Redefining argument with the local name 'arch' (redefined-argument-from-local)

Signed-off-by: Juerg Haefliger <juergh@proton.me>

annotations: Fix pylint violations

Fix the following:
R1722: Consider using sys.exit() (consider-using-sys-exit)
C0209: Formatting a regular string which could be a f-string (consider-using-f-string)
W0703: Catching too general exception Exception (broad-except)
W1514: Using open without explicitly specifying an encoding (unspecified-encoding)
C0411: standard import "from signal import signal, SIGPIPE, SIG_DFL" should be placed before "from kconfig.annotations import Annotation, KConfig" (wrong-import-order)

Signed-off-by: Juerg Haefliger <juergh@proton.me>

setup.cfg: Disable some overly conservative pylint checks

Disable some 'too-many-<foo>' and 'too-few-<bar>' checks which we don't
really care about too much :-).

Signed-off-by: Juerg Haefliger <juergh@proton.me>

Add 'pylint' target and config section

Signed-off-by: Juerg Haefliger <juergh@proton.me>

Fix flake8 violations

Signed-off-by: Juerg Haefliger <juergh@proton.me>

Add Makefile with initial 'lint' target

Signed-off-by: Juerg Haefliger <juergh@proton.me>

annotations: Check validity of FLAVOUR_DEP

FLAVOUR_DEP is used to map flavors from the main annotations file to
flavors from includes. Currently, there is no check that any of the
listed flavors exists or is valid so the resulting behavior is
(probably) undefined/unexpected. Add a sanity check to verify the
FLAVOUR_DEP flavors.

Signed-off-by: Juerg Haefliger <juerg.haefliger@canonical.com>
Signed-off-by: Andrea Righi <andrea.righi@canonical.com>

annotations: cleanups + always save configs with note at the top

Signed-off-by: Juerg Haefliger <juerg.haefliger@canonical.com>
Signed-off-by: Andrea Righi <andrea.righi@canonical.com>

annotations: support single-line rules

The old annotations scheme allowed single-line rules like:
CONFIG_FOO  policy<{..}> note<..>

With the switch to the new annotations script, we lost that capability.
This change brings it back.

Signed-off-by: Juerg Haefliger <juerg.haefliger@canonical.com>
Signed-off-by: Andrea Righi <andrea.righi@canonical.com>

annotations: fix _remove_entry() logic

Drop unnecessary delete statements and fix the code to properly remove
the entry in _remove_entry().

Reported-by: Juerg Haefliger <juerg.haefliger@canonical.com>
Signed-off-by: Andrea Righi <andrea.righi@canonical.com>

annotations: do not drop undefined configs in derivatives

Prevent dropping configs that are undefined across all the supported
architectures in annotations that have includes, because we may want to
use them to override configs imported from other annotations.

Signed-off-by: Andrea Righi <andrea.righi@canonical.com>

annotations: make sure to always drop undefined configs

Signed-off-by: Andrea Righi <andrea.righi@canonical.com>

annotations: add CONFIG_GCC_VERSION to the list of skipped configs

Signed-off-by: Andrea Righi <andrea.righi@canonical.com>

annotations: remove configs that are undefined across all arches/flavours

Sometimes certain config options are removed in new kernels, so when
annotations is updated these options result to be undefined across all
architectures and flavours, in this case it's much more clean to simply
drop them from annotations (considering that the kernel doesn't support
them anymore).

Signed-off-by: Andrea Righi <andrea.righi@canonical.com>

annotations: compact same value across all flavour within the same arch

Signed-off-by: Andrea Righi <andrea.righi@canonical.com>

annotations: do not add constraints on toolchain

Signed-off-by: Andrea Righi <andrea.righi@canonical.com>

annotations: do not enforce toolchain versions

Allow to use different versions of gcc, as and ld in the build ppa,
respect to the version used to produce the kernel packages.

Signed-off-by: Andrea Righi <andrea.righi@canonical.com>

annotations: add missing CONFIG_ prefix in main()

This is common for do_query(), do_note(), do_write() (and whatever
command might be added in the future).

Move it to main().

Signed-off-by: Masahiro Yamada <masahiro.yamada@canonical.com>
Signed-off-by: Andrea Righi <andrea.righi@canonical.com>

annotations: introduce --source

Add an option to jump to the definition of a specific config option in
the kernel source code (this requires a prior `make tags` to work).

Signed-off-by: Andrea Righi <andrea.righi@canonical.com>

annotations: add an option to enable config autocompletion in bash

Type `source <(annotations --autocomplete)` to enable auto-completion of
config options (without the CONFIG_ prefix) in bash when running
annotations script commands.

Signed-off-by: Andrea Righi <andrea.righi@canonical.com>

annotations: allow to specify --write and --note at the same time

Signed-off-by: Andrea Righi <andrea.righi@canonical.com>

annotations: prevent python broken pipe errors

Prevent broken pipe errors when showing output in pipe to other tools
(less for example).

Signed-off-by: Andrea Righi <andrea.righi@canonical.com>

annotations: prevent generating .pyc files on import

We may end up adding these files to our git repos by mistake, so simply
prevent generating them in advance.

There's a tiny performance penalty with this change, because python
needs to re-generate the bytecode on-the-fly every time the annotations
script is called, but this overhead is absolutely negligible compared
the rest of the kernel build time.

Signed-off-by: Andrea Righi <andrea.righi@canonical.com>

annotations: catch syntax errors in annotations

Trigger a syntax error when a policy or note rule is not properly
closed.

Signed-off-by: Andrea Righi <andrea.righi@canonical.com>

annotations: properly support multiple levels of inclusion

Moreover, do some refactoring to optimize parsing.

Signed-off-by: Andrea Righi <andrea.righi@canonical.com>

annotations: clarify error message with --import

Signed-off-by: Andrea Righi <andrea.righi@canonical.com>

annotations: accept config options with or without CONFIG_ prefix

Allow to specify config options with or without CONFIG_ prefix in the
commands --write and --note, to be consistent with --query that already
accepts both formats.

Reported-by: Masahiro Yamada <masahiro.yamada@canonical.com>
Signed-off-by: Andrea Righi <andrea.righi@canonical.com>

annotations: properly merge configs with includes

Signed-off-by: Andrea Righi <andrea.righi@canonical.com>

annotations: support flavour dependencies (flavour inheritance)

Allow to define flavour inheritance relationship in the annotations
file, such as:

  # FLAVOUR_DEP: {'amd64-lowlatency': 'amd64-generic', 'arm64-lowlatency': 'arm64-generic', 'arm64-lowlatency-64k': 'arm64-lowlatency-64k'}

In this case, for example, -lowlatency flavours inherits the config
values from -generic (both for amd64 and arm64) and -lowlatency-64
inherits the value from -generic-64k (only on arm64).

This allows to strongly reduce the size of annotations and helps to
read and review changes in annotations.

Signed-off-by: Andrea Righi <andrea.righi@canonical.com>

annotations: allow to query CONFIG_<option> or just <option>

Signed-off-by: Andrea Righi <andrea.righi@canonical.com>

annotations: allow to set notes directly and assume --query is the default command

Allow to set a note directly to a config option without changing any
value and also assume --query is the default command, so we don't have
to specify --query explicitly to query config options.

Signed-off-by: Andrea Righi <andrea.righi@canonical.com>

annotations: set and delete configs from command line

Allow to set and delete config options from command line using the
'annotations' script (instead of manually editing the annotations file).

This also provides an interface to manage the annotations file from
other scripts.

Signed-off-by: Andrea Righi <andrea.righi@canonical.com>

annotations: report config failures in alphabetical order

This allows to review config check failures across multiple
architectures.

Signed-off-by: Andrea Righi <andrea.righi@canonical.com>

annotations: provide --update command

Add a command to import a partial .config (instead of resycning a full
.config as --import does).

Signed-off-by: Andrea Righi <andrea.righi@canonical.com>

annotations: compact more redundant arch and flavours settings

Signed-off-by: Andrea Righi <andrea.righi@canonical.com>

doc: simplify commands in examples

Signed-off-by: Andrea Righi <andrea.righi@canonical.com>

annotations: avoid generating a KeyError exception

Always try to return None when a config is not defined in annotations
rather then throwing an exception.

Signed-off-by: Andrea Righi <andrea.righi@canonical.com>

annotations: allow to import/resync single config option

Signed-off-by: Andrea Righi <andrea.righi@canonical.com>

doc: update TODO list

Signed-off-by: Andrea Righi <andrea.righi@canonical.com>

annotations: properly handle dropped configs during import

Signed-off-by: Andrea Righi <andrea.righi@canonical.com>

annotations: check: catch options that are removed from the .config

Signed-off-by: Andrea Righi <andrea.righi@canonical.com>

annotations: make action argument mandatory

Signed-off-by: Andrea Righi <andrea.righi@canonical.com>

annotations: avoid converting null results to kconfig format

Signed-off-by: Andrea Righi <andrea.righi@canonical.com>

annotations: try to compact annotations before saving it

Signed-off-by: Andrea Righi <andrea.righi@canonical.com>

annotations: automatically detect annotations file location

Signed-off-by: Andrea Righi <andrea.righi@canonical.com>

doc: add a basic README.md

Signed-off-by: Andrea Righi <andrea.righi@canonical.com>