From d89d9ef1dbcae3cfca8ff8a39da6f77cc247e6e3 Mon Sep 17 00:00:00 2001 From: Ulf Magnusson Date: Mon, 6 Nov 2017 07:53:31 +0100 Subject: Polish the module documentation Doing a (hopefully) final pass through the docs before release. --- kconfiglib.py | 150 ++++++++++++++++++++++++++++++++++------------------------ 1 file changed, 89 insertions(+), 61 deletions(-) diff --git a/kconfiglib.py b/kconfiglib.py index d248aba..1d3bad6 100644 --- a/kconfiglib.py +++ b/kconfiglib.py @@ -3,44 +3,70 @@ Overview ======== Kconfiglib is a Python 2/3 library for scripting and extracting information -from Kconfig-based configuration systems. Features include the following: +from Kconfig configuration systems. Among other things, it can be used to do +the following: - - Programmatic getting and setting of symbol values + - Programmatically get and set symbol values - - Reading/writing of .config files + allnoconfig.py and allyesconfig.py examples are provided, automatically + verified to produce identical output to the standard 'make allnoconfig' and + 'make allyesconfig'. - - Inspection of symbol properties and expressions: printing a symbol (calling - Symbol.__str__()) gives output which could be fed back into a Kconfig parser - to redefine the symbol, and __str__() is implemented with only public APIs. -TODO: this isn't true anymore by default for choice symbols (though it could -be arranged by not printing the choice dependency) + - Read/write .config files - A helpful __repr__() is implemented on all objects as well, also implemented - with public APIs. + The generated .config files are character-for-character identical to what + the C implementation would generate (except for the header comment). The + test suite relies on this, as it compares the generated files. - - Expressions use a simple tuple-based format and can be processed manually if - needed. + - Inspect symbols - - Menu tree inspection: The underlying menu tree is exposed, including - submenus created implicitly from symbols depending on preceding symbols. - This can be used e.g. to implement menuconfig-like functionality. + Printing a symbol gives output which could be fed back into a Kconfig parser + to redefine it***. The printing function (__str__()) is implemented with + public APIs, meaning you can fetch just whatever information you need as + well. + + A helpful __repr__() is implemented on all objects too. + + ***Choice symbols get their parent choice as a dependency, which shows up as + e.g. 'prompt "choice symbol" if ' when printing the symbol. This + could easily be worked around if 100% reparsable output is needed. + + - Inspect expressions + + Expressions use a simple tuple-based format that can be processed manually + if needed. Expression printing and evaluation functions are provided, + implemented with public APIs. + + - Inspect the menu tree + + The underlying menu tree is exposed, including submenus created implicitly + from symbols depending on preceding symbols. This can be used e.g. to + implement menuconfig-like functionality. See the menuconfig.py example. + + +Here are some other features: - Runs under both Python 2 and 3. The code mostly uses basic Python features and has no third-party dependencies. The most advanced things used are - probably @property and __slots__. + probably @property and __slots__. The entire library is contained in this + file. - Robust and highly compatible with the standard Kconfig C tools: The test - suite automatically compares output from Kconfiglib and the C tools (by - diffing generated .config files) on the real kernel Kconfig and defconfig - files, for all ARCHes. All tests are expected to pass. + suite automatically compares output from Kconfiglib and the C tools by + diffing the generated .config files for the real kernel Kconfig and + defconfig files, for all ARCHes. This currently involves comparing the + output for 36 ARCHes and 498 defconfig files (or over 18000 ARCH/defconfig + combos in "obsessive" test suite mode). All tests are expected to pass. - A set of selftests is also included. + - Not horribly slow despite being a pure Python implementation: The + allyesconfig.py example currently runs in about 1.6 seconds on a Core i7 + 2600K (with a warm file cache), where half a second is overhead from + 'make scriptconfig' (see below). - - Not horribly slow despite being a pure Python implementation: Parses the x86 - Kconfigs in about a second on a Core i7 2600K (with a warm file cache). For - long-running jobs, PyPy gives a big performance boost. + For long-running jobs, PyPy gives a big performance boost. CPython is faster + for short-running jobs as PyPy needs some time to warm up. - - Internals that (mostly) mirror the C implementation while being simpler to + - Internals that (mostly) mirror the C implementation, while being simpler to understand. @@ -48,8 +74,8 @@ Using Kconfiglib on the Linux kernel with the Makefile targets ============================================================== For the Linux kernel, a handy interface is provided by the -scripts/kconfig/Makefile patch. See further down for a motivation for the -Makefile patch and for how to run Kconfiglib without it. +scripts/kconfig/Makefile patch. Look further down for a motivation for the +Makefile patch and for instructions on how you can use Kconfiglib without it. The Makefile patch adds the following targets: @@ -58,26 +84,21 @@ make [ARCH=] iscriptconfig -------------------------------- This target gives an interactive Python prompt where a Kconfig instance has -been preloaded and is available in 'k'. +been preloaded and is available in 'kconf'. To change the Python interpreter +used, pass PYTHONCMD= to make. The default is "python". To get a feel for the API, try evaluating and printing the symbols in -k.defined_syms, and explore the MenuNode menu tree starting at k.top_node by -following 'next' and 'list' pointers. +kconf.defined_syms, and explore the MenuNode menu tree starting at +kconf.top_node by following 'next' and 'list' pointers. -The item contained in a menu node is found in MenuNode.item, and all symbols -and choices have a 'nodes' attribute containing their menu nodes (usually only -one). Printing a menu node will print its item. +The item contained in a menu node is found in MenuNode.item (note that this can +be one of the constants MENU and COMMENT), and all symbols and choices have a +'nodes' attribute containing their menu nodes (usually only one). Printing a +menu node will print its item, in Kconfig format. If you want to look up a symbol by name, use the kconf.syms dictionary. -To change the Python interpreter used, pass PYTHONCMD= to make. The -default is "python". - -Tip: IronPython (PYTHONCMD=ipython) is handy when figuring out the API, as it -provides autocompletion for attributes. - - make scriptconfig SCRIPT=