Add a sample 'make scriptconfig'

To demonstrate some different possibilities. Will need to move some stuff around
later too.

1 files changed, 85 insertions, 0 deletions

diff --git a/README.rst b/README.rst
index d4a5f4a..c6d138a 100644
--- a/README.rst
+++ b/README.rst
@@ -147,6 +147,91 @@ Just drop it somewhere.
 Examples
 --------
 
+Sample ``make iscriptconfig`` session
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The following log should give some idea of the functionality available in the API:
+
+.. code-block::
+
+    $ make iscriptconfig
+    A Kconfig instance 'kconf' for the architecture x86 has been created.
+    >>> kconf  # Calls Kconfig.__repr__()
+    <configuration with 13711 symbols, main menu prompt "Linux/x86 4.14.0-rc7 Kernel Configuration", srctree ".", config symbol prefix "CONFIG_", warnings enabled, undef. symbol assignment warnings disabled>
+    >>> kconf.mainmenu_text  # Expanded main menu text
+    'Linux/x86 4.14.0-rc7 Kernel Configuration'
+    >>> kconf.top_node  # The implicit top-level menu
+    <menu node for menu, prompt "Linux/$ARCH $KERNELVERSION Kernel Configuration" (visibility y), deps y, 'visible if' deps y, has child, Kconfig:5>
+    >>> kconf.top_node.list  # First child menu node
+    <menu node for symbol SRCARCH, deps y, has next, Kconfig:7>
+    >>> print(kconf.top_node.list)  # Calls MenuNode.__str__()
+    config SRCARCH
+    	string
+    	option env="SRCARCH"
+    	default "x86"
+    
+    >>> sym = kconf.top_node.list.next.item  # Item contained in next menu node
+    >>> print(sym)  # Calls Symbol.__str__()
+    config 64BIT
+    	bool
+    	prompt "64-bit kernel" if ARCH = "x86"
+    	default ARCH != "i386"
+    	help
+    	  Say yes to build a 64-bit kernel - formerly known as x86_64
+    	  Say no to build a 32-bit kernel - formerly known as i386
+    
+    >>> sym  # Calls Symbol.__repr__()
+    <symbol 64BIT, bool, "64-bit kernel", value y, visibility y, direct deps y, arch/x86/Kconfig:2>
+    >>> sym.assignable  # Currently assignable values (0, 1, 2 = n, m, y)
+    (0, 2)
+    >>> sym.set_value(0)  # Set it to n
+    True
+    >>> sym.tri_value  # Check the new value
+    0
+    >>> sym = kconf.syms["X86_MPPARSE"]  # Look up symbol by name
+    >>> print(sym)
+    config X86_MPPARSE
+    	bool
+    	prompt "Enable MPS table" if (ACPI || SFI) && X86_LOCAL_APIC
+    	default "y" if X86_LOCAL_APIC
+    	help
+    	  For old smp systems that do not have proper acpi support. Newer systems
+    	  (esp with 64bit cpus) with acpi support, MADT and DSDT will override it
+    
+    >>> default = sym.defaults[0]  # Fetch its first default
+    >>> sym = default[1]  # Fetch the default's condition (just a Symbol here)
+    >>> print(sym)  # Print it. Dependencies are propagated to properties, like in the C implementation.
+    config X86_LOCAL_APIC
+    	bool
+    	default "y" if X86_64 || SMP || X86_32_NON_STANDARD || X86_UP_APIC || PCI_MSI
+    	select IRQ_DOMAIN_HIERARCHY if X86_64 || SMP || X86_32_NON_STANDARD || X86_UP_APIC || PCI_MSI
+    	select PCI_MSI_IRQ_DOMAIN if PCI_MSI && (X86_64 || SMP || X86_32_NON_STANDARD || X86_UP_APIC || PCI_MSI)
+    
+    >>> sym.nodes  # Show the MenuNode(s) associated with it
+    [<menu node for symbol X86_LOCAL_APIC, deps n, has next, arch/x86/Kconfig:1015>]
+    >>> kconfiglib.expr_str(sym.defaults[0][1])  # Print the default's condition
+    'X86_64 || SMP || X86_32_NON_STANDARD || X86_UP_APIC || PCI_MSI'
+    >>> kconfiglib.expr_value(sym.defaults[0][1])  # Evaluate it (0 = n)
+    0
+    >>> kconf.syms["64BIT"].set_value(2)
+    True
+    >>> kconfiglib.expr_value(sym.defaults[0][1])  # Evaluate it again (2 = y)
+    2
+    >>> kconf.write_config("myconfig")  # Save a .config
+    >>> ^D
+    $ cat myconfig
+    # Generated by Kconfiglib (https://github.com/ulfalizer/Kconfiglib)
+    CONFIG_64BIT=y
+    CONFIG_X86_64=y
+    CONFIG_X86=y
+    CONFIG_INSTRUCTION_DECODER=y
+    CONFIG_OUTPUT_FORMAT="elf64-x86-64"
+    CONFIG_ARCH_DEFCONFIG="arch/x86/configs/x86_64_defconfig"
+    CONFIG_LOCKDEP_SUPPORT=y
+    CONFIG_STACKTRACE_SUPPORT=y
+    CONFIG_MMU=y
+    ...
+
 * The `examples/ <https://github.com/ulfalizer/Kconfiglib/tree/master/examples>`_ directory contains simple example scripts. See the documentation for how to run them.
 
 * `genboardscfg.py <http://git.denx.de/?p=u-boot.git;a=blob;f=tools/genboardscfg.py;hb=HEAD>`_ from `Das U-Boot <http://www.denx.de/wiki/U-Boot>`_ generates some sort of legacy board database by pulling information from a newly added Kconfig-based configuration system (as far as I understand it :).