From 7d06f6fd219711752a499c2d29c18998579bd18c Mon Sep 17 00:00:00 2001 From: Chloe Dancey <22119302+novo52@users.noreply.github.com> Date: Tue, 18 Aug 2026 16:15:01 -0600 Subject: [PATCH 1/6] Add a table style that wraps cell text instead of scrolling --- info/_static/css/tables.css | 5 +++++ info/conf.py | 1 + 2 files changed, 6 insertions(+) create mode 100644 info/_static/css/tables.css diff --git a/info/_static/css/tables.css b/info/_static/css/tables.css new file mode 100644 index 00000000..567c0c31 --- /dev/null +++ b/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; +} diff --git a/info/conf.py b/info/conf.py index e263ecd3..ee221a9d 100644 --- a/info/conf.py +++ b/info/conf.py @@ -73,6 +73,7 @@ # or fully qualified paths (eg. https://...) html_css_files = [ 'css/googleFonts.css', + 'css/tables.css', ] # Disable syntax highlighting in code blocks From 9a0505dda8d58f6c8ebeb307bc174fe293d997bf Mon Sep 17 00:00:00 2001 From: Chloe Dancey <22119302+novo52@users.noreply.github.com> Date: Tue, 18 Aug 2026 16:15:01 -0600 Subject: [PATCH 2/6] Give VCalc and Gazprea an Architecture page listing the required passes --- gazprea/impl/architecture.rst | 15 +++++++++++++++ gazprea/index.rst | 1 + vcalc/impl/architecture.rst | 13 +++++++++++++ vcalc/index.rst | 1 + 4 files changed, 30 insertions(+) create mode 100644 gazprea/impl/architecture.rst create mode 100644 vcalc/impl/architecture.rst diff --git a/gazprea/impl/architecture.rst b/gazprea/impl/architecture.rst new file mode 100644 index 00000000..c3b62e39 --- /dev/null +++ b/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 `grading criteria `_. All six properties apply to *Gazprea*. diff --git a/gazprea/index.rst b/gazprea/index.rst index 347686af..c7570be0 100644 --- a/gazprea/index.rst +++ b/gazprea/index.rst @@ -40,6 +40,7 @@ Hardware Acceleration Laboratory in Markham, ON. :maxdepth: 2 :caption: Implementation + impl/architecture impl/backend impl/part_1 impl/part_2 diff --git a/vcalc/impl/architecture.rst b/vcalc/impl/architecture.rst new file mode 100644 index 00000000..366991ba --- /dev/null +++ b/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 `grading criteria `_. 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. diff --git a/vcalc/index.rst b/vcalc/index.rst index 1152b3bf..d483f428 100644 --- a/vcalc/index.rst +++ b/vcalc/index.rst @@ -39,6 +39,7 @@ grammar works as expected. :maxdepth: 2 :caption: Implementation + impl/architecture impl/input impl/output impl/assertions From c2c3db48ccd378007bff8dbcda1d34c0ba2da93c Mon Sep 17 00:00:00 2001 From: Chloe Dancey <22119302+novo52@users.noreply.github.com> Date: Tue, 18 Aug 2026 16:15:01 -0600 Subject: [PATCH 3/6] Assess architecture properties as part of the design mark --- info/grading.rst | 44 +++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 43 insertions(+), 1 deletion(-) diff --git a/info/grading.rst b/info/grading.rst index 60cf9e81..fbb86a74 100644 --- a/info/grading.rst +++ b/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 `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 `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 ---------------------- From 1c0daea3f323c9c6621d059f1e70c0190418a898 Mon Sep 17 00:00:00 2001 From: Chloe Dancey <22119302+novo52@users.noreply.github.com> Date: Tue, 18 Aug 2026 16:29:03 -0600 Subject: [PATCH 4/6] Make the cross-site architecture links relative --- gazprea/impl/architecture.rst | 2 +- info/grading.rst | 4 ++-- vcalc/impl/architecture.rst | 2 +- 3 files changed, 4 insertions(+), 4 deletions(-) diff --git a/gazprea/impl/architecture.rst b/gazprea/impl/architecture.rst index c3b62e39..1d463a2f 100644 --- a/gazprea/impl/architecture.rst +++ b/gazprea/impl/architecture.rst @@ -12,4 +12,4 @@ You should write your compiler as a series of passes each with simple functional 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 `grading criteria `_. All six properties apply to *Gazprea*. +These passes are also assessed against the architecture properties listed under Design in the `grading criteria <../../info/grading.html>`_. All six properties apply to *Gazprea*. diff --git a/info/grading.rst b/info/grading.rst index fbb86a74..5b877afa 100644 --- a/info/grading.rst +++ b/info/grading.rst @@ -29,13 +29,13 @@ 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 `Architecture `__. + The passes your compiler must have are listed under `Architecture <../vcalc/impl/architecture.html>`__. * **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 `Architecture `__. + The passes your compiler must have are listed under `Architecture <../gazprea/impl/architecture.html>`__. Architecture Properties diff --git a/vcalc/impl/architecture.rst b/vcalc/impl/architecture.rst index 366991ba..66daa5ec 100644 --- a/vcalc/impl/architecture.rst +++ b/vcalc/impl/architecture.rst @@ -8,6 +8,6 @@ You should write your compiler as a series of passes each with simple functional * 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 `grading criteria `_. Five of the six apply to *VCalc*. +These passes are also assessed against the architecture properties listed under Design in the `grading criteria <../../info/grading.html>`_. 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. From 1a9b42a7cbc519fb4ef7a8224dc70117edcb5e86 Mon Sep 17 00:00:00 2001 From: Chloe Dancey <22119302+novo52@users.noreply.github.com> Date: Tue, 18 Aug 2026 16:44:08 -0600 Subject: [PATCH 5/6] Wire info and vcalc into each other's intersphinx mapping --- info/conf.py | 22 +++++++++++----------- vcalc/conf.py | 22 +++++++++++----------- 2 files changed, 22 insertions(+), 22 deletions(-) diff --git a/info/conf.py b/info/conf.py index 28bc6a3b..76f17bbd 100644 --- a/info/conf.py +++ b/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 ``..//_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+:doc:`` when that is actually what is meant. intersphinx_disabled_reftypes = ['std:doc'] # Toggles the display of "Todo" message boxes in the output diff --git a/vcalc/conf.py b/vcalc/conf.py index eb7f978a..3097b75b 100644 --- a/vcalc/conf.py +++ b/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 ``..//_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+:doc:`` when that is actually what is meant. intersphinx_disabled_reftypes = ['std:doc'] # Toggles the display of "Todo" message boxes in the output From 81d49e2d186a43e323cc91d8a474e489f0e8b97b Mon Sep 17 00:00:00 2001 From: Chloe Dancey <22119302+novo52@users.noreply.github.com> Date: Tue, 18 Aug 2026 16:44:08 -0600 Subject: [PATCH 6/6] Reference the architecture and grading pages through intersphinx --- gazprea/impl/architecture.rst | 2 +- info/grading.rst | 4 ++-- vcalc/impl/architecture.rst | 2 +- 3 files changed, 4 insertions(+), 4 deletions(-) diff --git a/gazprea/impl/architecture.rst b/gazprea/impl/architecture.rst index 1d463a2f..1d65b880 100644 --- a/gazprea/impl/architecture.rst +++ b/gazprea/impl/architecture.rst @@ -12,4 +12,4 @@ You should write your compiler as a series of passes each with simple functional 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 `grading criteria <../../info/grading.html>`_. All six properties apply to *Gazprea*. +These passes are also assessed against the architecture properties listed under Design in the :external+info:doc:`grading criteria `. All six properties apply to *Gazprea*. diff --git a/info/grading.rst b/info/grading.rst index 5b877afa..648d31a7 100644 --- a/info/grading.rst +++ b/info/grading.rst @@ -29,13 +29,13 @@ 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 `Architecture <../vcalc/impl/architecture.html>`__. + The passes your compiler must have are listed under :external+vcalc:doc:`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 `Architecture <../gazprea/impl/architecture.html>`__. + The passes your compiler must have are listed under :external+gazprea:doc:`Architecture `. Architecture Properties diff --git a/vcalc/impl/architecture.rst b/vcalc/impl/architecture.rst index 66daa5ec..981d1253 100644 --- a/vcalc/impl/architecture.rst +++ b/vcalc/impl/architecture.rst @@ -8,6 +8,6 @@ You should write your compiler as a series of passes each with simple functional * 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 `grading criteria <../../info/grading.html>`_. Five of the six apply to *VCalc*. +These passes are also assessed against the architecture properties listed under Design in the :external+info:doc:`grading criteria `. 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.