Document watcom_util.py

makeprojects/watcom_util.py

@@ -14,6 +14,7 @@
 
 from burger import is_string, convert_to_linux_slashes
 
+from .util import iterate_configurations
 from .validators import lookup_enum_value
 from .enums import FileTypes, PlatformTypes, ProjectTypes
 from .hlsl_support import HLSL_ENUMS, make_hlsl_command
@@ -23,17 +24,18 @@
 
 
 def fixup_env(item):
-    """
+    r"""
     Check if a path has an environment variable.
-    If an pathname starts with $(XXX), then it needs to be invoking
-    and environment variable. Watcom uses the form $(%XXX) so insert a
-    percent sign to convert if needed
+    If an pathname starts with \$(XXX), then it needs to be invoking
+    an environment variable. Watcom uses the form $(%%XXX) so insert a
+    percent sign to convert to Watcom format if needed. If it already
+    has a percent sign, don't change the string.
 
     Args:
         item: String to check
 
     Returns:
-        Updated pathname using $(%XXX) format
+        Updated pathname using $(%%XXX) format
     """
 
     # Convert the macros
@@ -47,9 +49,19 @@ def fixup_env(item):
 
 
 def convert_file_name_watcom(item):
-    """
+    r"""
     Convert macros from Visual Studio to Open Watcom
 
+    This table shows the conversions
+
+    | Visual Studio | Watcom |
+    | ------------- | ------ |
+    | %(RootDir)%(Directory) | $[: |
+    | %(FileName) | $[& |
+    | %(FullPath) | $[@ |
+    | %(Identity) | $[@ |
+    | \$(TargetPath) | $^@ |
+
     Args:
         item: Filename string
     Returns:
@@ -76,6 +88,13 @@ def get_element_dict(rule_list, base_name, tool_enums):
     dict with all the keys and values for the Visual Studio overrides
     for this file.
 
+    This is usually parsed by the HLSL and GLSL command generators.
+
+    Note:
+        The returned value is a dict using Visual Studio elements as keys
+        with the parameter template string as the value. Example keys are
+        ``ObjectFileName``, ``VariableName``, and ``HeaderFileName``.
+
     Args:
         rule_list: Iterable of a list of rules
         base_name: Name of the source file to check
@@ -93,15 +112,15 @@ def get_element_dict(rule_list, base_name, tool_enums):
     for rule in rule_list:
 
         # The key is a regex
-        for key in rule:
+        for file_regex in rule:
 
             # Match the filename?
-            if not key(base_name):
+            if not file_regex(base_name):
                 # No? Skip it
                 continue
 
             # Get the list of records
-            records = rule[key]
+            records = rule[file_regex]
             for item in records:
                 value = records[item]
 
@@ -122,16 +141,27 @@ def get_element_dict(rule_list, base_name, tool_enums):
     # Return the generated dict
     return element_dict
 
-
 ########################################
 
 
 def get_custom_list(custom_list, rule_list, codefiles):
     """
-    Scan the custom rules and create a list of bespoke builders
+    Scan the custom rules and create a list of bespoke builders.
+
+    First, convert the rule list into the Visual Studio dictionaries,
+    and then use the GLSL or HLSL command line generators to create
+
+    Next, iterate over the codefiles for any GLSL or HLSL files and
+    apply the rules (If found) and create the command lines needed
+    to build the files.
+
+    If any custom build commands are generated, they are appended to
+    ``custom_list`` as a 4 entry tuple, with the first entry being the
+    command line, the second is a text description of the command, the
+    third is the name of the output file(s) and lastly the input filename.
 
     Args:
-        custom: list object to receive new entries
+        custom_list: list object to receive new entries
         rule_list: Tuple of rules
         codefiles: List of SourceFile objects to check
 
@@ -190,11 +220,17 @@ def get_output_list(custom_list):
     """
     Scan the custom_list and return the output files
 
+    Create a list of output filenames and sort them before returning
+    the list. The third entry of the ``custom_list`` is the output filename.
+
     Args:
         custom_list: List of custom commands
 
     Return:
         List of output file names
+
+    See Also:
+        get_custom_list
     """
 
     # Use a set to remove duplicates
@@ -203,14 +239,14 @@ def get_output_list(custom_list):
     # Scan the list
     for item in custom_list:
 
-        # Add every output file
+        # Add every output file to the set
         for output in item[2]:
             output_list.add(output)
 
     # Convert to a linked list
     output_list = list(output_list)
 
-    # Sort it
+    # Sort it and exit
     output_list.sort()
     return output_list
 
@@ -227,10 +263,13 @@ def get_obj_list(codefiles, type_list):
 
     Args:
         codefiles: Codefiles list from the project
-        type_list: List of FileType enum objects
+        type_list: List of enums.FileTypes objects
 
     Returns:
         List of processed matching filenames, or empty list
+
+    See Also:
+        enums.FileTypes
     """
 
     # Create result list
@@ -268,11 +307,11 @@ def get_obj_list(codefiles, type_list):
 
 
 def add_obj_list(line_list, obj_list, prefix, suffix):
-    """
+    r"""
     Create a list of object files with prefix
 
     Give a list of filenames without extensions, create
-    a Watcom compatible list with an $(A) prefix for runtime
+    a Watcom compatible list with an \$(A) prefix for runtime
     pathname substitution. Add the supplied prefix to all
     filenames.
 
@@ -301,9 +340,15 @@ def add_post_build(line_list, configuration):
     """
     If there are custom build rules, add them
 
+    Scan the configuration attribute ``post_build`` and if
+    it exists, append the commands to ``line_list``.
+
     Args:
         line_list: Output stream
         configuration: Project configuration
+
+    See Also:
+        convert_file_name_watcom, fixup_env
     """
 
     # Is there custom post build rule?
@@ -334,7 +379,7 @@ def watcom_linker_system(configuration):
     Determine the watcom system for linkage
 
     Scan the configuration and return the string "system ???"
-    where ??? is replaces with dos4g, nt, etc.
+    where ??? is replaced with dos4g, nt, etc.
 
     Can be overriden with the attribute ``wat_system``. If this
     exists, use it to declare "system ???" or "" to disable.
@@ -376,3 +421,38 @@ def watcom_linker_system(configuration):
             system = "nt"
 
     return "system " + system
+
+########################################
+
+
+def warn_if_invalid(solution):
+    """
+    Iterate over the solution and determine if there are errors
+
+    Test for use of use_mfc or use_atl
+
+    Args:
+        solution: Reference to a solution record
+
+    Returns:
+        Zero if no error, non-zero if error
+    """
+
+    # Create sets of configuration names and projects
+    for configuration in iterate_configurations(solution):
+
+        # Only test on windows platforms
+        if configuration.platform.is_windows():
+            # Test for MFC
+            if configuration.use_mfc:
+                print(
+                    "Watcom doesn't support Microsoft Foundation "
+                    "Classes, use_mfc must be False")
+
+            # Test for MFC
+            if configuration.use_atl:
+                print(
+                    "Watcom doesn't support Active Template Library, "
+                    "use_atl must be False")
+
+    return 0