Repository: ESMCI/cime

Issue:
Add empty "environment_variables" section in env_mach_specific.xml
It would be nice if the generated `env_mach_specific.xml` file contained an empty section for user-defined env variables, perhaps with a commented out example. This would allow the user to know exactly how to specify additional env vars.


Discussion:
This would be for machines that may have little, if anything, in their environment setup in config_machines.xml.
@bartgol @jgfouca  Hi Luca I am still learning more about the env_mach_specific.xml generation for each generated case on a specific machine. Could you tell me more about the goal for this task?

So you would like to have the system recognize when a machine listed in config_machines.xml has no entries for "environment_variables", an example of this would be the "oic5" machine. And when the system recognizes this situation it should insert this commented out example into the generated env_mach_specific.xml file located in the case directory.
`<!--environment_variables> <env name="NAME">ARGUMENT</env> </environment_variables-->`

Am I understanding this correctly?
@WesCoomber , yes, that sounds right. The idea is that, if the user wanted to make some temporary env changes in their case, they'd have a template they could follow.

Resolving patch:
diff --git a/scripts/lib/CIME/XML/env_mach_specific.py b/scripts/lib/CIME/XML/env_mach_specific.py
--- a/scripts/lib/CIME/XML/env_mach_specific.py
+++ b/scripts/lib/CIME/XML/env_mach_specific.py
@@ -35,6 +35,10 @@ def populate(self, machobj):
 
         for item in items:
             nodes = machobj.get_first_child_nodes(item)
+            if item == "environment_variables":
+                if len(nodes) == 0:
+                    example_text = """This section is for the user to specify any additional machine-specific env var, or to overwite existing ones.\n  <environment_variables>\n    <env name="NAME">ARGUMENT</env>\n  </environment_variables>\n  """
+                    self.make_child_comment(text = example_text)
             if item == "run_exe" or item == "run_misc_suffix":
                 if len(nodes) == 0:
                     value = self.text(default_run_exe_node) if item == "run_exe" else self.text(default_run_misc_suffix_node)
diff --git a/scripts/lib/CIME/XML/generic_xml.py b/scripts/lib/CIME/XML/generic_xml.py
--- a/scripts/lib/CIME/XML/generic_xml.py
+++ b/scripts/lib/CIME/XML/generic_xml.py
@@ -241,6 +241,15 @@ def make_child(self, name, attributes=None, root=None, text=None):
 
         return node
 
+    def make_child_comment(self, root=None, text=None):
+        expect(not self.locked and not self.read_only, "{}: cannot make child {} in file {}".format("read_only" if self.read_only else "locked", text, self.filename))
+        root = root if root is not None else self.root
+        self.needsrewrite = True
+        et_comment = ET.Comment(text)
+        node = _Element(et_comment)
+        root.xml_element.append(node.xml_element)
+        return node
+
     def get_children(self, name=None, attributes=None, root=None):
         """
         This is the critical function, its interface and performance are crucial.


Test patch: