Six architecture properties as part of design mark

gazprea/impl/architecture.rst

@@ -0,0 +1,15 @@
+.. _sec:architecture:
+
+Architecture
+============
+
+You should write your compiler as a series of passes each with simple functionality. Do not implement your compiler as a single pass. As a minimum, your compiler should have individual passes that perform each of the following actions:
+
+* Create an abstract syntax tree.
+* Define symbols and ensure that symbols can be referenced in the locations they are used. These actions may be performed by two separate passes.
+* Propagate type information through expressions and perform static type checking. These actions may be performed by two separate passes.
+* Emit LLVM, SCF, Memref and Arith Dialects that can be lowered into LLVM IR.
+
+Your compiler should use a symbol table to track symbol definitions and scopes.
+
+These passes are also assessed against the architecture properties listed under Design in the :external+info:doc:`grading criteria <grading>`. All six properties apply to *Gazprea*.

gazprea/index.rst

@@ -41,6 +41,7 @@ Hardware Acceleration Laboratory in Markham, ON.
    :maxdepth: 2
    :caption: Implementation
 
+   impl/architecture
    impl/backend
    impl/part_1
    impl/part_2

info/_static/css/tables.css

@@ -0,0 +1,5 @@
+/* The RTD theme sets white-space: nowrap on table cells, which forces wide
+ * tables horizontally scrollable. Tables marked .wrap-table wrap instead. */
+.wrap-table td, .wrap-table th {
+    white-space: normal !important;
+}

info/conf.py

@@ -33,22 +33,22 @@
     'sphinx.ext.intersphinx',
 ]
 
-# Cross-reference the Gazprea glossary.  The tuple's first element is the
+# Cross-reference sibling projects.  The tuple's first element is the
 # canonical URL used to rewrite resolved refs; the second element is a list
-# of inventory-source fallbacks.  ``../gazprea/_build/html/objects.inv``
-# resolves against this file's directory, so ``make all`` (which builds
-# gazprea first per the top-level Makefile) always finds the inventory
-# locally.  If the local file is missing, intersphinx falls back to the
-# published URL and the build still succeeds.
+# of inventory-source fallbacks.  Each ``../<project>/_build/html/objects.inv``
+# resolves against this file's directory, so ``make all`` finds the inventory
+# locally for any project the top-level Makefile builds earlier.  If the local
+# file is missing, intersphinx falls back to the published URL and the build
+# still succeeds.
 intersphinx_mapping = {
-    'gazprea': (
-        'https://cmput415.github.io/415-docs/gazprea',
-        ('../gazprea/_build/html/objects.inv', None),
-    ),
+    'gazprea':   ('https://cmput415.github.io/415-docs/gazprea',
+                  ('../gazprea/_build/html/objects.inv', None)),
+    'vcalc':     ('https://cmput415.github.io/415-docs/vcalc',
+                  ('../vcalc/_build/html/objects.inv', None)),
 }
 
 # Never let a bare :doc:`foo` silently resolve to a sibling project's page;
-# force ``:external+gazprea:doc:`` when that is actually what is meant.
+# force ``:external+<project>:doc:`` when that is actually what is meant.
 intersphinx_disabled_reftypes = ['std:doc']
 
 # Toggles the display of "Todo" message boxes in the output
@@ -102,6 +102,7 @@
 # or fully qualified paths (eg. https://...)
 html_css_files = [
     'css/googleFonts.css',
+    'css/tables.css',
 ]
 
 # Disable syntax highlighting in code blocks

info/grading.rst

@@ -29,11 +29,53 @@ product: scalability, flexibility, and maintainability.
     You need to design an AST and Symbol table, and use them to implement
     multiple passes including: symbol definitions, symbol resolutions and
     semantic checking, type checking, and code generation.
+    The passes your compiler must have are listed under :external+vcalc:doc:`Architecture <impl/architecture>`.
 
   * **Gazprea** While the top-level architecture is almost identical to
     *VCalc*, the rich type system within can increase complexity
     substantially unless it is managed. It is also important to understand
     and select dialects that make sense for your design.
+    The passes your compiler must have are listed under :external+gazprea:doc:`Architecture <impl/architecture>`.
+
+
+Architecture Properties
+^^^^^^^^^^^^^^^^^^^^^^^
+
+Part of the design mark is the following properties of your implementation, assessed by inspection of your code. Each is marked separately, and only on the projects marked below. None of them apply to *Generator*.
+
+.. list-table::
+   :header-rows: 1
+   :widths: 76 8 8 8
+   :class: wrap-table
+
+   * - **Property**
+     - LOLCODE
+     - VCalc
+     - Gazprea
+   * - **Types are decided once.** Your emission pass must not compute or infer the type of an expression. It reads type information recorded by an earlier pass.
+     -
+     - ✓
+     - ✓
+   * - **One source of truth for conversions.** The rules deciding whether a conversion is legal and the code performing that conversion must not be two lists kept in agreement by hand. If they are separate, something in your build must check that they agree.
+     - ✓
+     - ✓
+     - ✓
+   * - **Pass dependencies are written down.** Each pass must state what it requires to already be true when it runs. If reordering two of your passes breaks your compiler, that dependency must appear somewhere a reader can find it.
+     -
+     - ✓
+     - ✓
+   * - **Element-wise operations share their emission.** Adding a new operator over vectors or matrices must not require writing new index arithmetic.
+     -
+     - ✓
+     - ✓
+   * - **Names are resolved once.** Your emission pass must not look a name up by string. Symbol resolution happens in an earlier pass, and later passes use the resolved symbol.
+     -
+     - ✓
+     - ✓
+   * - **Locations are recorded at construction.** Every node carries the source location it came from, assigned when the node is built.
+     -
+     -
+     - ✓
 
 Software Engineering Processes
 ------------------------------
@@ -92,7 +134,7 @@ Code Style and Consistency
 * You are expected to separate class definitions from implementations using header (.h) and source (.cpp)
   files.
 * Your code should be clean and readable.
-* There is no minimum expectation for commenting or documentation.
+* There is no minimum expectation for commenting or documentation, except where the design requirements require a design decision to be recorded.
 
 TA Specification Tests
 ----------------------

vcalc/conf.py

@@ -33,22 +33,22 @@
     'sphinx.ext.intersphinx',
 ]
 
-# Cross-reference the Gazprea glossary.  The tuple's first element is the
+# Cross-reference sibling projects.  The tuple's first element is the
 # canonical URL used to rewrite resolved refs; the second element is a list
-# of inventory-source fallbacks.  ``../gazprea/_build/html/objects.inv``
-# resolves against this file's directory, so ``make all`` (which builds
-# gazprea first per the top-level Makefile) always finds the inventory
-# locally.  If the local file is missing, intersphinx falls back to the
-# published URL and the build still succeeds.
+# of inventory-source fallbacks.  Each ``../<project>/_build/html/objects.inv``
+# resolves against this file's directory, so ``make all`` finds the inventory
+# locally for any project the top-level Makefile builds earlier.  If the local
+# file is missing, intersphinx falls back to the published URL and the build
+# still succeeds.
 intersphinx_mapping = {
-    'gazprea': (
-        'https://cmput415.github.io/415-docs/gazprea',
-        ('../gazprea/_build/html/objects.inv', None),
-    ),
+    'gazprea':   ('https://cmput415.github.io/415-docs/gazprea',
+                  ('../gazprea/_build/html/objects.inv', None)),
+    'info':      ('https://cmput415.github.io/415-docs/info',
+                  ('../info/_build/html/objects.inv', None)),
 }
 
 # Never let a bare :doc:`foo` silently resolve to a sibling project's page;
-# force ``:external+gazprea:doc:`` when that is actually what is meant.
+# force ``:external+<project>:doc:`` when that is actually what is meant.
 intersphinx_disabled_reftypes = ['std:doc']
 
 # Toggles the display of "Todo" message boxes in the output

vcalc/impl/architecture.rst

@@ -0,0 +1,13 @@
+.. _sec:vcalc_architecture:
+
+Architecture
+============
+
+You should write your compiler as a series of passes each with simple functionality. Do not implement your compiler as a single pass. As a minimum, your compiler should have individual passes that perform each of the following actions:
+
+* Create an abstract syntax tree.
+* Emit LLVM, SCF, Memref and Arith Dialects that can be lowered into LLVM IR.
+
+These passes are also assessed against the architecture properties listed under Design in the :external+info:doc:`grading criteria <grading>`. Five of the six apply to *VCalc*.
+
+Some VCalc designs do not carry over to Gazprea. Gazprea has multiple scalar types with promotion between them, nested tuple types, matrices and strings alongside vectors, assignable expressions other than plain identifiers, and routines callable before they are defined. A VCalc compiler can reasonably assume a single scalar type, a flat type tag, a one-dimensional vector representation, and one value per expression; none of these assumptions hold in Gazprea. Consider this when choosing how to represent types and values.

vcalc/index.rst

@@ -39,6 +39,7 @@ grammar works as expected.
    :maxdepth: 2
    :caption: Implementation
 
+   impl/architecture
    impl/input
    impl/output
    impl/assertions