Merge branch 'master' into Issue5

Author: vulder

.github/ISSUE_TEMPLATE/topic-proposal.md

@@ -3,7 +3,7 @@ name: Topic proposal
 about: Describes a topic that should be considered by SG20 for education guidelines
 title: "[TOPIC-REQUEST]"
 labels: Needs triaging
-assignees: BobSteagall, cjdb, jcvw
+assignees: vulder, jcvw
 
 ---
 

.github/workflows/release.yml

@@ -23,7 +23,7 @@ jobs:
     - name: Collect git metadata
       id: git_metadata
       run: |
-        echo "{VERSION}::{${GITHUB_REF#refs/tags/v}}" >> $GITHUB_OUTPUT
+        echo "VERSION=${GITHUB_REF#refs/tags/v}" >> $GITHUB_OUTPUT
     # The following builds the document in multiple formats for deployment.
     - name: Build the document.
       shell: bash

sources/Makefile

@@ -115,7 +115,7 @@ knowledge_areas_summary.md: $(SOURCES) knowledge_areas.dat
 	$(MAKE_MARKDOWN) < knowledge_areas.dat > knowledge_areas_summary.md
 
 contributors.md:
-	git log --all --pretty="%aN" | sort | uniq > contributors.md
+	git log --format="%aN%n%(trailers:key=Co-authored-by,valueonly=true)" | sed 's/ <.*>//g' | sort | uniq > contributors.md
 
 ################################################################################
 # Establish Pandoc settings.

sources/knowledge_areas.dat

@@ -55,6 +55,11 @@ EH Error Handling
 	? ? ? ? errno
 	? ? ? ? Error Codes
 	eh y y y Exception Handling
+PD Program Design
+	cont y y y Containers
+DE Debugging Errors
+	compiletimeerr y y y Compile-Time Errors
+	runtimeerr y y y Run-time Errors
 SL Standard Library
 	? ? ? ? Input/Output (I/O)
 	? ? ? ? Containers, Iterators, and Algorithms

sources/modules/compilation-model/buildsystems.md

@@ -0,0 +1,115 @@
+## Module name: Build systems
+
+_Skeleton descriptions are typeset in italic text,_
+_so please don't remove these descriptions when editing the topic._
+
+### Overview
+
+_Provides a short natural language abstract of the module’s contents._
+_Specifies the different levels of teaching._
+
+------------------------------------------------------------------------
+Level             Objective
+----------------- ------------------------------------------------------
+Foundational      --- Knowledge about build systems
+
+Main              --- Usage of build system to compile a executable
+
+Advanced          --- Add external libraries as a dependencies  
+
+------------------------------------------------------------------------
+
+### Motivation
+
+_Why is this important?_
+_Why do we want to learn/teach this topic?_
+
+* Building complex C++ projects by hand is tricky
+* Build systems can help to resolve dependencies
+* Build systems can help do distribute C++ code and help other to compile the code
+* Build systems can help to find and include libraries as dependencies
+* Build systems faciliate project management 
+* All major C++ projects are distributed with build systems 
+
+### Topic introduction
+
+_Very brief introduction to the topic._
+
+Build systems are used to configure, build, and install complex C++ projects. 
+
+
+### Foundational: Knowledge about build systems
+
+#### Background/Required Knowledge
+
+A student: 
+* Should know how to compile and link C++ programs
+
+
+#### Student outcomes
+
+_A list of things "a student should be able to" after the curriculum._
+_The next word should be an action word and testable in an exam._
+_Max 5 items._
+
+A student should be able to:
+
+1. To explain what a build system is
+2. To explain that a build systems resolves dependencies
+3. To explain that a build system supports compilation for different operating systems and architectures
+
+#### Caveats
+
+_This section mentions subtle points to understand, like anything resulting in
+implementation-defined, unspecified, or undefined behavior._
+
+None
+
+#### Points to cover
+
+_This section lists important details for each point._
+
+* Mention that many build systems are available for C++ 
+* Mention benefits and challenges
+* Build system help to only compile the C++ files with code changes and not the complete project
+
+### Main: Usage of build system to compile a executable
+
+#### Background/Required Knowledge
+
+* All of the above.
+
+#### Student outcomes
+
+A student should be able to:
+
+1. Download a C++ package and build the package
+2. Write a configuration file to compile a C++ executable
+3. Pass compiler options via the build system
+4. Use the build system to generate the executable
+5. Write a configuration file to compile a library and link the library to a C++ executable
+
+#### Caveats
+
+The instructions are restricted to the chosen build system and
+not easily transferable.
+
+
+#### Points to cover
+
+* Include paths to header files to the configuration 
+* Adding compiler flags
+* How to build Release and Debug builds
+* Linking external libraries to the C++ project
+* Support compilation on different operating systems, compilers, and architectures 
+
+
+### Advanced
+
+_These are important topics that are not expected to be covered but provide
+guidance where one can continue to investigate this topic in more depth._
+
+* How to build libraries 
+* How to have external libraries be downloaded during the build process
+* Mention that build systems provide support for unit testing
+

sources/modules/debugging-errors/build-errors.md

@@ -0,0 +1,6 @@
+## Debugging Errors: Build errors
+
+_Skeleton descriptions are typeset in italic text,_
+_so please don't remove these descriptions when editing the topic._
+
+This topic is currently under construction and will soon be filled with information :)

sources/modules/debugging-errors/compiletime-errors.md

@@ -0,0 +1,114 @@
+## Debugging Errors: Compile-time errors {#compiletimeerr}
+
+_Skeleton descriptions are typeset in italic text,_
+_so please don't remove these descriptions when editing the topic._
+
+### Overview
+
+_Provides a short natural language abstract of the module’s contents._
+_Specifies the different levels of teaching._
+
+------------------------------------------------------------------------
+Level             Objective
+----------------- ------------------------------------------------------
+Foundational      Understanding elementary error messages
+
+Main              Dealing with most error messages
+
+Advanced          ---
+
+------------------------------------------------------------------------
+
+### Motivation
+
+_Why is this important?_
+_Why do we want to learn/teach this topic?_
+
+Compiler error messages can be hard to read and even compiler specific.
+However, they contain valuable information for determining the cause of the compile-time errors.
+Oftentimes the error messages are very verbose to give you the most precise information about the error context, so learning how to extract the valuable information from the error message is an important skill that one should acquire.
+
+### Topic introduction
+
+_Very brief introduction to the topic._
+
+C++ compilers try to statically determine errors at compile time to shift detection of problems that would occur later on (e.g., at link time or run time) to earlier point in time, where they can be addressed in an earlier stage of the development process.
+The error message that the compiler generates directly relates to the C++ language definition and precisely lays out why the code is not valid and where it does not comply with the language rules.
+
+### Foundational: Understanding elementary error messages {#compiletimeerr-found}
+
+#### Background/Required Knowledge
+
+A student:
+
+* definitions [[C++ Object Model: Definitions - Foundational]][1]
+
+#### Student outcomes
+
+_A list of things "a student should be able to" after the curriculum._
+_The next word should be an action word and testable in an exam._
+_Max 5 items._
+
+A student should be able to:
+
+1. distill the core of an elementary error message.
+2. act on elementary error messages.
+3. differentiate between different error kinds (e.g., type errors, syntax errors, ...).
+4. give examples for different kinds of errors.
+
+
+#### Caveats
+
+_This section mentions subtle points to understand, like anything resulting in
+implementation-defined, unspecified, or undefined behavior._
+
+* names mentioned in error message are presented in full detail and may not look exactly like specified by the programmer (e.g., `std::string` -> `std::basic_string<char>`)
+
+#### Points to cover
+
+_This section lists important details for each point._
+
+* methodology of reading error messages
+    * start with the first error
+    * read top down
+    * parse error message / pattern matching to error kinds
+* linker errors [[Debugging Errors: Build errors - Foundational]][2]
+
+
+### Main: Dealing with most error messages {#compiletimeerr-main}
+
+#### Background/Required Knowledge
+
+* compile-time programming [Soft dependency]
+
+#### Student outcomes
+
+A student should be able to:
+
+1. locate the principle template involved in a template error message.
+2. determine why a specific overload is chosen, from the compiler’s error message.
+3. apply common debugging techniques in a constexpr context.
+
+#### Caveats
+
+* argument dependent lookup
+* there is currently no good debugger support for constexpr context
+
+#### Points to cover
+
+* templates related error messages
+* overload resolution related errors
+* reasoning about errors during constexpr execution (consteval)
+    * reverting to non-constexpr run-time debugging
+    * employing static_assert
+
+### Advanced
+
+_These are important topics that are not expected to be covered but provide
+guidance where one can continue to investigate this topic in more depth._
+
+* Full error analysis, there are error messages that are out of the scope for students.
+    * Complicated SFINAE constructs
+
+[1]: ../object-model/definitions.md
+[2]: ../debugging-errors/build-errors.md

sources/modules/debugging-errors/runtime-errors.md

@@ -0,0 +1,113 @@
+## Debugging errors: Run-time errors {#runtimeerr}
+
+_Skeleton descriptions are typeset in italic text,_
+_so please don't remove these descriptions when editing the topic._
+
+### Overview
+
+_Provides a short natural language abstract of the module’s contents._
+_Specifies the different levels of teaching._
+
+------------------------------------------------------------------------
+Level             Objective
+----------------- ------------------------------------------------------
+Foundational      Identifying the run-time error cause
+
+Main              Introspection methodologies to trackdown run-time errors
+
+Advanced          ---
+
+------------------------------------------------------------------------
+
+### Motivation
+
+_Why is this important?_
+_Why do we want to learn/teach this topic?_
+
+Code correctness is important, as erroneous programs can lead to real-world catastrophes, take for example, medical equipment failures that lead to people being exposed to too much radiation.
+Techniques, such as, testing or fuzzing, help developers to identify erroneous states of the program.
+However, when these techniques discover a run-time error, it’s up to the programmer to reason about and find the root cause of such run-time errors, so they need a well established process to debug run-time errors.
+
+### Topic introduction
+
+_Very brief introduction to the topic._
+
+There exists a wide variety of methodologies, techniques, and tools to debug run-time errors.
+In this topic, we give an overview of these and highlight how they can be applied to track down run-time errors in C++ programs.
+
+### Foundational: Identifying the run-time error cause {#runtimeerr-found}
+
+#### Background/Required Knowledge
+
+A student:
+
+* should be able to produce a basic running program.
+
+#### Student outcomes
+
+_A list of things "a student should be able to" after the curriculum._
+_The next word should be an action word and testable in an exam._
+_Max 5 items._
+
+A student should be able to:
+
+1. verify the output of the program and identify incorrect outcomes.
+2. phrase hypothesis what could cause the run-time error.
+3. observe and extract program state at specific points of the program, to verify hypotheses.
+4. make their program as observable as possible.
+
+#### Caveats
+
+_This section mentions subtle points to understand, like anything resulting in
+implementation-defined, unspecified, or undefined behavior._
+
+* run-time debugging can be domain specific
+* not everything about the program state can be easily observed, students should be aware of that and learn basic techniques to make programs more observable
+* students should be aware that the compilation mode (optimized vs debug) affects the debugging experience and also the program state itself
+
+
+#### Points to cover
+
+_This section lists important details for each point._
+
+* the basics of using a debugger
+* compiling with debug information
+* observability techniques, such as, logging output or even `printf` statements
+
+### Main: Introspection methodologies to trackdown run-time errors {#runtimeerr-main}
+
+#### Background/Required Knowledge
+
+* All of the above.
+
+#### Student outcomes
+
+A student should be able to:
+
+1. use a debugger to inspect and manipulate program state
+2. extract crash information using proper libraries
+3. can create a minimal reproducible example
+
+#### Caveats
+
+* Different forms of multiprocessing programs can have varying impact on debuggability, such as:
+    * parallel stl algorithms
+    * multi threading
+    * coroutines
+    * vector parallelism
+
+
+#### Points to cover
+
+* How to use debuggers and the multitude of features they offer to manipulate and observe program state (e.g., break points, trap points, stack traces, manipulating program state).
+* Use (non) standard library support for crash information extraction, e.g., logging libraries, libraries to capture crash reports, and sanitizer libraries (asan/ubsan/tsan).
+* Creating minimal reproducible example and regressions tests from the extracted crash information.
+
+
+### Advanced {#runtimeerr-advanced}
+
+_These are important topics that are not expected to be covered but provide
+guidance where one can continue to investigate this topic in more depth._
+
+* ABI incompatibilities can have impact debugging experience where even observability tools, such as, debuggers, cannot correctly show the state of the program.
+* Debugging in embedded environments.