From f91d3c583c7b75663ea70c6248f156fe4540a861 Mon Sep 17 00:00:00 2001
From: "Anthony G. Basile" <blueness@gentoo.org>
Date: Tue, 14 Jul 2015 17:23:50 -0400
Subject: grs/Kernel.py: add documentation.

---
 grs/Kernel.py | 27 +++++++++++++++++++++++----
 1 file changed, 23 insertions(+), 4 deletions(-)

(limited to 'grs')

diff --git a/grs/Kernel.py b/grs/Kernel.py
index 16d2247..c04f5a5 100644
--- a/grs/Kernel.py
+++ b/grs/Kernel.py
@@ -9,8 +9,10 @@ from grs.Execute import Execute
 
 
 class Kernel():
+    """ Build a linux-image pkg and install when building a system. """
 
-    def __init__(self, libdir = CONST.LIBDIR, portage_configroot = CONST.PORTAGE_CONFIGROOT, kernelroot = CONST.KERNELROOT, package = CONST.PACKAGE, logfile = CONST.LOGFILE):
+    def __init__(self, libdir = CONST.LIBDIR, portage_configroot = CONST.PORTAGE_CONFIGROOT, \
+            kernelroot = CONST.KERNELROOT, package = CONST.PACKAGE, logfile = CONST.LOGFILE):
         self.libdir = libdir
         self.portage_configroot = portage_configroot
         self.kernelroot = kernelroot
@@ -20,18 +22,24 @@ class Kernel():
 
 
     def parse_kernel_config(self):
+        """ Parse the version to be built/installed from the kernel-config file. """
         with open(self.kernel_config, 'r') as f:
             for i in range(3):
                 line = f.readline()
+        # The version line looks like the following:
+        # Linux/x86 4.0.6-hardened-r2 Kernel Configuration
+        # The 2nd group contains the version.
         m = re.search('^#\s+(\S+)\s+(\S+).+$', line)
         gentoo_version = m.group(2)
         try:
+            # Either the verison is of the form '4.0.6-hardened-r2' with two -'s
             m = re.search('(\S+?)-(\S+?)-(\S+)', gentoo_version)
             vanilla_version = m.group(1)
             flavor = m.group(2)
             revision = m.group(3)
             pkg_name = flavor + '-sources-' + vanilla_version + '-' + revision
         except AttributeError:
+            # Or the verison is of the form '4.0.6-hardened' with one -
             m = re.search('(\S+?)-(\S+)', gentoo_version)
             vanilla_version = m.group(1)
             flavor = m.group(2)
@@ -41,25 +49,35 @@ class Kernel():
 
 
     def kernel(self):
+        """ This emerges the kernel sources to a directory outside of the
+            fledgeling system's portage configroot, builds and installs it
+            to yet another external directory, bundles the kernel and modules
+            as a .tar.xz in the packages directory for downloads via grsup,
+            and finally installs it to the system's portage configroot.
+        """
+        # Grab the parsed verison and pkg atom.
         (gentoo_version, pkg_name) = self.parse_kernel_config()
 
+        # Prepare the paths to where we'll emerge and build the kernel,
+        # as well as paths for genkernel.
         kernel_source = os.path.join(self.kernelroot, 'usr/src/linux')
         image_dir     = os.path.join(self.kernelroot, gentoo_version)
         boot_dir      = os.path.join(image_dir, 'boot')
         modprobe_dir  = os.path.join(image_dir, 'etc/modprobe.d')
         modules_dir   = os.path.join(image_dir, 'lib/modules')
 
-        # Remove any old image directory and create a boot directory
-        # wich genkernel assumes is present.
+        # Remove any old kernel image directory and create a boot directory.
+        # Note genkernel assumes a boot directory is present.
         shutil.rmtree(image_dir, ignore_errors=True)
         os.makedirs(boot_dir, mode=0o755, exist_ok=True)
 
+        # emerge the kernel source.
         cmd = 'emerge --nodeps -1n %s' % pkg_name
         emerge_env = { 'USE' : 'symlink', 'ROOT' : self.kernelroot, 'ACCEPT_KEYWORDS' : '**' }
         Execute(cmd, timeout=600, extra_env=emerge_env, logfile=self.logfile)
 
         # Build and install the image outside the portage configroot so
-        # we can both rsync it in *and* tarball it for downloads.
+        # we can both rsync it in *and* tarball it for downloads via grsup.
         # TODO: add more options (eg splash and firmware), which can be
         # specified vi the kernel line in the build script.
         cmd = 'genkernel '
@@ -77,6 +95,7 @@ class Kernel():
         cmd += 'all'
         Execute(cmd, timeout=None, logfile=self.logfile)
 
+        # Strip the modules to shrink their size enormously!
         for dirpath, dirnames, filenames in os.walk(modules_dir):
             for filename in filenames:
                 if filename.endswith('.ko'):
-- 
cgit v1.2.3-65-gdbad