From 92a9a34aa8bfb5cb776b108624a628e1f12f5e3a Mon Sep 17 00:00:00 2001 From: Victor Eijkhout Date: Fri, 26 Jul 2024 09:33:39 -0500 Subject: [PATCH 01/25] Create separate-compilation.md create from skeleton --- .../compilation-model/separate-compilation.md | 84 +++++++++++++++++++ 1 file changed, 84 insertions(+) create mode 100644 sources/modules/compilation-model/separate-compilation.md diff --git a/sources/modules/compilation-model/separate-compilation.md b/sources/modules/compilation-model/separate-compilation.md new file mode 100644 index 0000000..2cc384e --- /dev/null +++ b/sources/modules/compilation-model/separate-compilation.md @@ -0,0 +1,84 @@ +## Module name: topic name + +_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 --- + +Main --- + +Advanced --- + +------------------------------------------------------------------------ + +### Motivation + +_Why is this important?_ +_Why do we want to learn/teach this topic?_ + +### Topic introduction + +_Very brief introduction to the topic._ + +### Foundational: Using * + +#### Background/Required Knowledge + +A student: + + +#### 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. +2. +3. +4. +5. + +#### Caveats + +_This section mentions subtle points to understand, like anything resulting in +implementation-defined, unspecified, or undefined behavior._ + +#### Points to cover + +_This section lists important details for each point._ + +### Main: implementing * + +#### Background/Required Knowledge + +* All of the above. + +#### Student outcomes + +A student should be able to: + +1. +2. +3. +4. +5. + +#### Caveats + +#### Points to cover + +### 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._ From c42254b10179d5e9efe3e1dbf6c91b5f8768f3ba Mon Sep 17 00:00:00 2001 From: Victor Eijkhout Date: Thu, 29 Aug 2024 10:50:09 -0500 Subject: [PATCH 02/25] victor first stab at separate compilation --- .../compilation-model/separate-compilation.md | 40 +++++++++++++------ 1 file changed, 28 insertions(+), 12 deletions(-) diff --git a/sources/modules/compilation-model/separate-compilation.md b/sources/modules/compilation-model/separate-compilation.md index 2cc384e..684cd6e 100644 --- a/sources/modules/compilation-model/separate-compilation.md +++ b/sources/modules/compilation-model/separate-compilation.md @@ -1,4 +1,4 @@ -## Module name: topic name +## Module name: Separate Compilation _Skeleton descriptions are typeset in italic text,_ _so please don't remove these descriptions when editing the topic._ @@ -11,11 +11,11 @@ _Specifies the different levels of teaching._ ------------------------------------------------------------------------ Level Objective ----------------- ------------------------------------------------------ -Foundational --- +Foundational Awareness of the existence of separate compilation -Main --- +Main Awareness of supporting mechanisms and tools -Advanced --- +Advanced Awareness of technicalities and tools ------------------------------------------------------------------------ @@ -24,15 +24,21 @@ Advanced --- _Why is this important?_ _Why do we want to learn/teach this topic?_ +Any non-trivial program will span more than one source file. This makes separate compilation necessary. Separate compilation also leads to quick build times in projects under development. + ### Topic introduction _Very brief introduction to the topic._ -### Foundational: Using * +### Foundational: Using #### Background/Required Knowledge -A student: +A student: + +1. needs to be able to split a single-file program into multiple files. +2. needs to understand the difference between declaration and definition. + #### Student outcomes @@ -43,8 +49,8 @@ _Max 5 items._ A student should be able to: -1. -2. +1. Split a single file program into main, one or more auxiliaries, and header files (or modules), all in one directory +2. Compile and link a program that is spread over multiple files (again, all in one directory), either on the commandline or with a build system. 3. 4. 5. @@ -54,11 +60,15 @@ A student should be able to: _This section mentions subtle points to understand, like anything resulting in implementation-defined, unspecified, or undefined behavior._ +1. Explain differences (including in desirability) between having explicit declarations of functions in the main program versus using header files or modules. +2. Compilation on a single commandline versus multiple +3. What needs to be recompiled if only a function is altered? Altered in use syntax versus altered only in semantics. + #### Points to cover _This section lists important details for each point._ -### Main: implementing * +### Main: implementing #### Background/Required Knowledge @@ -68,17 +78,23 @@ _This section lists important details for each point._ A student should be able to: -1. -2. -3. +1. Use compile flags, including `-I` and `-L` search path flags, and the relation with corresponding include directives in the source. +2. Understand search paths to use header files of external libraries. +3. Be able to declare `extern` variables. 4. 5. #### Caveats +1. CMake makes things both easier and harder. If CMake is used, cover the various `target_include/link` statements and discovery mechanisms for external libraries. + #### Points to cover ### 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._ + +1. Language inter-operability: the `extern "C"` mechanism. +2. Linker conventions including name mangling. +3. The `nm` tool for inspection object files and libraries. From ba6de1b3e201a667ee40b8ad1187f58b86f00883 Mon Sep 17 00:00:00 2001 From: Victor Eijkhout Date: Fri, 30 Aug 2024 09:48:21 -0500 Subject: [PATCH 03/25] shuffling stuff around --- .../compilation-model/separate-compilation.md | 27 ++++++++++--------- 1 file changed, 15 insertions(+), 12 deletions(-) diff --git a/sources/modules/compilation-model/separate-compilation.md b/sources/modules/compilation-model/separate-compilation.md index 684cd6e..8a48861 100644 --- a/sources/modules/compilation-model/separate-compilation.md +++ b/sources/modules/compilation-model/separate-compilation.md @@ -8,14 +8,16 @@ _so please don't remove these descriptions when editing the topic._ _Provides a short natural language abstract of the module’s contents._ _Specifies the different levels of teaching._ +This module outlines the issues involved in using separate compilation on multiple program files. + ------------------------------------------------------------------------ Level Objective ----------------- ------------------------------------------------------ -Foundational Awareness of the existence of separate compilation +Foundational: Awareness of the existence of separate compilation -Main Awareness of supporting mechanisms and tools +Main: Awareness of supporting mechanisms and tools -Advanced Awareness of technicalities and tools +Advanced: Awareness of technicalities and tools ------------------------------------------------------------------------ @@ -36,11 +38,10 @@ _Very brief introduction to the topic._ A student: -1. needs to be able to split a single-file program into multiple files. +1. needs to have the text editor skills to split a single-file program into multiple files. 2. needs to understand the difference between declaration and definition. - #### Student outcomes _A list of things "a student should be able to" after the curriculum._ @@ -55,19 +56,20 @@ A student should be able to: 4. 5. +#### Points to cover + +1. Necessity of having function be declared at the locus of use +2. Solving this by explicit declaration or by using header files. + #### Caveats _This section mentions subtle points to understand, like anything resulting in implementation-defined, unspecified, or undefined behavior._ 1. Explain differences (including in desirability) between having explicit declarations of functions in the main program versus using header files or modules. -2. Compilation on a single commandline versus multiple +2. Compilation on a single commandline versus multiple. Resolution order when linking. 3. What needs to be recompiled if only a function is altered? Altered in use syntax versus altered only in semantics. -#### Points to cover - -_This section lists important details for each point._ - ### Main: implementing #### Background/Required Knowledge @@ -78,8 +80,8 @@ _This section lists important details for each point._ A student should be able to: -1. Use compile flags, including `-I` and `-L` search path flags, and the relation with corresponding include directives in the source. -2. Understand search paths to use header files of external libraries. +1. Use compile flags, including `-I` and `-L` search path flags +2. Understand the relation between search paths include directives of header files of external libraries. 3. Be able to declare `extern` variables. 4. 5. @@ -98,3 +100,4 @@ guidance where one can continue to investigate this topic in more depth._ 1. Language inter-operability: the `extern "C"` mechanism. 2. Linker conventions including name mangling. 3. The `nm` tool for inspection object files and libraries. +4. Include guards on header files. From d84acea030dd2d2b77559a70b28ecca8dc41689a Mon Sep 17 00:00:00 2001 From: Victor Eijkhout Date: Thu, 26 Sep 2024 10:42:51 -0500 Subject: [PATCH 04/25] Update separate-compilation.md Edits after SG20 committee discussion. --- .../compilation-model/separate-compilation.md | 24 +++++++++---------- 1 file changed, 12 insertions(+), 12 deletions(-) diff --git a/sources/modules/compilation-model/separate-compilation.md b/sources/modules/compilation-model/separate-compilation.md index 8a48861..9f08443 100644 --- a/sources/modules/compilation-model/separate-compilation.md +++ b/sources/modules/compilation-model/separate-compilation.md @@ -39,7 +39,7 @@ _Very brief introduction to the topic._ A student: 1. needs to have the text editor skills to split a single-file program into multiple files. -2. needs to understand the difference between declaration and definition. +2. needs to be able to split function and classes into their declaration and definition. #### Student outcomes @@ -52,9 +52,8 @@ A student should be able to: 1. Split a single file program into main, one or more auxiliaries, and header files (or modules), all in one directory 2. Compile and link a program that is spread over multiple files (again, all in one directory), either on the commandline or with a build system. -3. -4. -5. +3. Describe the functions of the various files involved: source, object, executable. + #### Points to cover @@ -80,18 +79,19 @@ implementation-defined, unspecified, or undefined behavior._ A student should be able to: -1. Use compile flags, including `-I` and `-L` search path flags -2. Understand the relation between search paths include directives of header files of external libraries. -3. Be able to declare `extern` variables. -4. -5. +1. Use compile flags, including `-I` and `-L` search path flags. +2. Make header files for their own code, including using header guards. +3. Use include directives for the headers of external libraries. +5. Be able to declare `extern` variables. #### Caveats -1. CMake makes things both easier and harder. If CMake is used, cover the various `target_include/link` statements and discovery mechanisms for external libraries. +1. Build systems make things both easier and harder. #### Points to cover +1. Cover the mechanisms for include and library paths to your own code, as well as discovery mechanisms for external libraries. + ### Advanced _These are important topics that are not expected to be covered but provide @@ -99,5 +99,5 @@ guidance where one can continue to investigate this topic in more depth._ 1. Language inter-operability: the `extern "C"` mechanism. 2. Linker conventions including name mangling. -3. The `nm` tool for inspection object files and libraries. -4. Include guards on header files. +3. The `nm` tool for inspection object files and libraries, including de-mangling. +4. Understand the issues involved in deciding between include guards and `#pragma once`. From 45635e07e4cb758db31c3097f0754a770ad16892 Mon Sep 17 00:00:00 2001 From: Victor Eijkhout Date: Fri, 4 Oct 2024 10:00:27 -0500 Subject: [PATCH 05/25] Update sources/modules/compilation-model/separate-compilation.md Co-authored-by: Florian Sattler --- sources/modules/compilation-model/separate-compilation.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/sources/modules/compilation-model/separate-compilation.md b/sources/modules/compilation-model/separate-compilation.md index 9f08443..a3aa482 100644 --- a/sources/modules/compilation-model/separate-compilation.md +++ b/sources/modules/compilation-model/separate-compilation.md @@ -1,4 +1,4 @@ -## Module name: Separate Compilation +## C++ compilation model: Separate Compilation {#separate-comp} _Skeleton descriptions are typeset in italic text,_ _so please don't remove these descriptions when editing the topic._ From 1022ea24143b61c7e46d23ae73b44233ae5c45a4 Mon Sep 17 00:00:00 2001 From: Victor Eijkhout Date: Fri, 4 Oct 2024 10:02:26 -0500 Subject: [PATCH 06/25] Update sources/modules/compilation-model/separate-compilation.md Co-authored-by: Florian Sattler --- sources/modules/compilation-model/separate-compilation.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/sources/modules/compilation-model/separate-compilation.md b/sources/modules/compilation-model/separate-compilation.md index a3aa482..9538d20 100644 --- a/sources/modules/compilation-model/separate-compilation.md +++ b/sources/modules/compilation-model/separate-compilation.md @@ -39,7 +39,7 @@ _Very brief introduction to the topic._ A student: 1. needs to have the text editor skills to split a single-file program into multiple files. -2. needs to be able to split function and classes into their declaration and definition. +2. needs to be able to split function and classes into their declaration and definition. [[C++ object model: declarations]][1] [[C++ object model: Definitions]][2] #### Student outcomes From 96bb44565035d16953817ad5c61303ba0a274070 Mon Sep 17 00:00:00 2001 From: Victor Eijkhout Date: Fri, 4 Oct 2024 10:03:17 -0500 Subject: [PATCH 07/25] Update sources/modules/compilation-model/separate-compilation.md Co-authored-by: Florian Sattler --- sources/modules/compilation-model/separate-compilation.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/sources/modules/compilation-model/separate-compilation.md b/sources/modules/compilation-model/separate-compilation.md index 9538d20..2a993ac 100644 --- a/sources/modules/compilation-model/separate-compilation.md +++ b/sources/modules/compilation-model/separate-compilation.md @@ -101,3 +101,6 @@ guidance where one can continue to investigate this topic in more depth._ 2. Linker conventions including name mangling. 3. The `nm` tool for inspection object files and libraries, including de-mangling. 4. Understand the issues involved in deciding between include guards and `#pragma once`. + +[1]: ../object-model/declarations.md +[2]: ../object-model/definitions.md From bf8faefb68582fc3c5461ac38c8dfdbc41a89e42 Mon Sep 17 00:00:00 2001 From: Victor Eijkhout Date: Fri, 4 Oct 2024 10:03:56 -0500 Subject: [PATCH 08/25] Update sources/modules/compilation-model/separate-compilation.md Co-authored-by: Florian Sattler --- sources/modules/compilation-model/separate-compilation.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/sources/modules/compilation-model/separate-compilation.md b/sources/modules/compilation-model/separate-compilation.md index 2a993ac..16becb9 100644 --- a/sources/modules/compilation-model/separate-compilation.md +++ b/sources/modules/compilation-model/separate-compilation.md @@ -79,7 +79,7 @@ implementation-defined, unspecified, or undefined behavior._ A student should be able to: -1. Use compile flags, including `-I` and `-L` search path flags. +1. Use compile flags, including `-I` and `-L` to specify search paths. 2. Make header files for their own code, including using header guards. 3. Use include directives for the headers of external libraries. 5. Be able to declare `extern` variables. From 0b0d33a9868de120f34d61bc15cc6e3b2588d7d7 Mon Sep 17 00:00:00 2001 From: Victor Eijkhout Date: Fri, 4 Oct 2024 10:04:28 -0500 Subject: [PATCH 09/25] Update sources/modules/compilation-model/separate-compilation.md Co-authored-by: Florian Sattler --- sources/modules/compilation-model/separate-compilation.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/sources/modules/compilation-model/separate-compilation.md b/sources/modules/compilation-model/separate-compilation.md index 16becb9..727623f 100644 --- a/sources/modules/compilation-model/separate-compilation.md +++ b/sources/modules/compilation-model/separate-compilation.md @@ -82,7 +82,7 @@ A student should be able to: 1. Use compile flags, including `-I` and `-L` to specify search paths. 2. Make header files for their own code, including using header guards. 3. Use include directives for the headers of external libraries. -5. Be able to declare `extern` variables. +4. Be able to declare `extern` variables. #### Caveats From 25620d99daf69085081d33ec3ef5745190ee52e0 Mon Sep 17 00:00:00 2001 From: Victor Eijkhout Date: Fri, 4 Oct 2024 10:04:55 -0500 Subject: [PATCH 10/25] Update sources/modules/compilation-model/separate-compilation.md Co-authored-by: Florian Sattler --- sources/modules/compilation-model/separate-compilation.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/sources/modules/compilation-model/separate-compilation.md b/sources/modules/compilation-model/separate-compilation.md index 727623f..6e4087f 100644 --- a/sources/modules/compilation-model/separate-compilation.md +++ b/sources/modules/compilation-model/separate-compilation.md @@ -90,7 +90,7 @@ A student should be able to: #### Points to cover -1. Cover the mechanisms for include and library paths to your own code, as well as discovery mechanisms for external libraries. +* Cover the mechanisms for include and library paths to your own code, as well as discovery mechanisms for external libraries. ### Advanced From 49f1a5604c992ad57eb6903a73635fc2cb7287db Mon Sep 17 00:00:00 2001 From: Victor Eijkhout Date: Fri, 4 Oct 2024 10:05:43 -0500 Subject: [PATCH 11/25] Update sources/modules/compilation-model/separate-compilation.md Co-authored-by: Florian Sattler --- sources/modules/compilation-model/separate-compilation.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/sources/modules/compilation-model/separate-compilation.md b/sources/modules/compilation-model/separate-compilation.md index 6e4087f..c89d3ce 100644 --- a/sources/modules/compilation-model/separate-compilation.md +++ b/sources/modules/compilation-model/separate-compilation.md @@ -50,9 +50,9 @@ _Max 5 items._ A student should be able to: -1. Split a single file program into main, one or more auxiliaries, and header files (or modules), all in one directory -2. Compile and link a program that is spread over multiple files (again, all in one directory), either on the commandline or with a build system. -3. Describe the functions of the various files involved: source, object, executable. +1. split a single file program into main, one or more auxiliaries, and header files (or modules), all in one directory +2. compile and link a program that is spread over multiple files (again, all in one directory), either on the commandline or with a build system. +3. describe the functions of the various files involved: source, object, executable. #### Points to cover From 55ec0c2af40452db483bcc8f6a74a962b938318c Mon Sep 17 00:00:00 2001 From: Victor Eijkhout Date: Fri, 4 Oct 2024 10:06:26 -0500 Subject: [PATCH 12/25] Update sources/modules/compilation-model/separate-compilation.md Co-authored-by: Florian Sattler --- sources/modules/compilation-model/separate-compilation.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/sources/modules/compilation-model/separate-compilation.md b/sources/modules/compilation-model/separate-compilation.md index c89d3ce..7923dd9 100644 --- a/sources/modules/compilation-model/separate-compilation.md +++ b/sources/modules/compilation-model/separate-compilation.md @@ -57,8 +57,8 @@ A student should be able to: #### Points to cover -1. Necessity of having function be declared at the locus of use -2. Solving this by explicit declaration or by using header files. +* Necessity of having function be declared at the locus of use +* Solving this by explicit declaration or by using header files. #### Caveats From b698abe8701da35dc12c2d036ab18b069da90bdb Mon Sep 17 00:00:00 2001 From: Victor Eijkhout Date: Thu, 31 Oct 2024 10:31:47 -0500 Subject: [PATCH 13/25] Update separate-compilation.md intro text moved to motivation --- sources/modules/compilation-model/separate-compilation.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/sources/modules/compilation-model/separate-compilation.md b/sources/modules/compilation-model/separate-compilation.md index 7923dd9..6e33a7b 100644 --- a/sources/modules/compilation-model/separate-compilation.md +++ b/sources/modules/compilation-model/separate-compilation.md @@ -8,8 +8,6 @@ _so please don't remove these descriptions when editing the topic._ _Provides a short natural language abstract of the module’s contents._ _Specifies the different levels of teaching._ -This module outlines the issues involved in using separate compilation on multiple program files. - ------------------------------------------------------------------------ Level Objective ----------------- ------------------------------------------------------ @@ -26,6 +24,8 @@ Advanced: Awareness of technicalities and tools _Why is this important?_ _Why do we want to learn/teach this topic?_ +This module outlines the issues involved in using separate compilation on multiple program files. + Any non-trivial program will span more than one source file. This makes separate compilation necessary. Separate compilation also leads to quick build times in projects under development. ### Topic introduction From 2e82bd950c488593ddeab87e1836508074063e2b Mon Sep 17 00:00:00 2001 From: Victor Eijkhout Date: Thu, 31 Oct 2024 10:33:45 -0500 Subject: [PATCH 14/25] Update separate-compilation.md remove mention of text editor --- sources/modules/compilation-model/separate-compilation.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/sources/modules/compilation-model/separate-compilation.md b/sources/modules/compilation-model/separate-compilation.md index 6e33a7b..9d131a1 100644 --- a/sources/modules/compilation-model/separate-compilation.md +++ b/sources/modules/compilation-model/separate-compilation.md @@ -38,8 +38,7 @@ _Very brief introduction to the topic._ A student: -1. needs to have the text editor skills to split a single-file program into multiple files. -2. needs to be able to split function and classes into their declaration and definition. [[C++ object model: declarations]][1] [[C++ object model: Definitions]][2] +1. needs to be able to split function and classes into their declaration and definition. [[C++ object model: declarations]][1] [[C++ object model: Definitions]][2] #### Student outcomes From 4f6a10a8c4462083910833d23aab152026f2c453 Mon Sep 17 00:00:00 2001 From: Victor Eijkhout Date: Thu, 31 Oct 2024 10:44:54 -0500 Subject: [PATCH 15/25] Update separate-compilation.md sub indent --- sources/modules/compilation-model/separate-compilation.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/sources/modules/compilation-model/separate-compilation.md b/sources/modules/compilation-model/separate-compilation.md index 9d131a1..20718a8 100644 --- a/sources/modules/compilation-model/separate-compilation.md +++ b/sources/modules/compilation-model/separate-compilation.md @@ -57,7 +57,7 @@ A student should be able to: #### Points to cover * Necessity of having function be declared at the locus of use -* Solving this by explicit declaration or by using header files. + * Solving this by explicit declaration or by using header files. #### Caveats From 5125283a4ef032a74df17043370bbbffa7e2b178 Mon Sep 17 00:00:00 2001 From: Victor Eijkhout Date: Thu, 31 Oct 2024 10:46:45 -0500 Subject: [PATCH 16/25] Update separate-compilation.md turn enum list into item --- sources/modules/compilation-model/separate-compilation.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/sources/modules/compilation-model/separate-compilation.md b/sources/modules/compilation-model/separate-compilation.md index 20718a8..9d26c2f 100644 --- a/sources/modules/compilation-model/separate-compilation.md +++ b/sources/modules/compilation-model/separate-compilation.md @@ -64,9 +64,9 @@ A student should be able to: _This section mentions subtle points to understand, like anything resulting in implementation-defined, unspecified, or undefined behavior._ -1. Explain differences (including in desirability) between having explicit declarations of functions in the main program versus using header files or modules. -2. Compilation on a single commandline versus multiple. Resolution order when linking. -3. What needs to be recompiled if only a function is altered? Altered in use syntax versus altered only in semantics. +* Explain differences (including in desirability) between having explicit declarations of functions in the main program versus using header files or modules. +* Compilation on a single commandline versus multiple. Resolution order when linking. +* What needs to be recompiled if only a function is altered? Altered in use syntax versus altered only in semantics. ### Main: implementing From cea2214834a990fe842da506dc4a72632e249e4e Mon Sep 17 00:00:00 2001 From: Victor Eijkhout Date: Thu, 31 Oct 2024 10:49:08 -0500 Subject: [PATCH 17/25] Update separate-compilation.md remove incorrect sentence --- sources/modules/compilation-model/separate-compilation.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/sources/modules/compilation-model/separate-compilation.md b/sources/modules/compilation-model/separate-compilation.md index 9d26c2f..4639136 100644 --- a/sources/modules/compilation-model/separate-compilation.md +++ b/sources/modules/compilation-model/separate-compilation.md @@ -65,7 +65,7 @@ _This section mentions subtle points to understand, like anything resulting in implementation-defined, unspecified, or undefined behavior._ * Explain differences (including in desirability) between having explicit declarations of functions in the main program versus using header files or modules. -* Compilation on a single commandline versus multiple. Resolution order when linking. +* Compilation on a single commandline versus using multiple commands. * What needs to be recompiled if only a function is altered? Altered in use syntax versus altered only in semantics. ### Main: implementing From a3030978587eccf6405fde90f128fd416f51f6b4 Mon Sep 17 00:00:00 2001 From: Victor Eijkhout Date: Thu, 31 Oct 2024 10:50:24 -0500 Subject: [PATCH 18/25] Update separate-compilation.md better caption --- sources/modules/compilation-model/separate-compilation.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/sources/modules/compilation-model/separate-compilation.md b/sources/modules/compilation-model/separate-compilation.md index 4639136..5840880 100644 --- a/sources/modules/compilation-model/separate-compilation.md +++ b/sources/modules/compilation-model/separate-compilation.md @@ -32,7 +32,7 @@ Any non-trivial program will span more than one source file. This makes separate _Very brief introduction to the topic._ -### Foundational: Using +### Foundational: Basic use of separate compilation #### Background/Required Knowledge From f5f70a4bf5c364a93b29324dce255e42eee018a8 Mon Sep 17 00:00:00 2001 From: Victor Eijkhout Date: Thu, 31 Oct 2024 10:52:00 -0500 Subject: [PATCH 19/25] Update separate-compilation.md better caption --- sources/modules/compilation-model/separate-compilation.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/sources/modules/compilation-model/separate-compilation.md b/sources/modules/compilation-model/separate-compilation.md index 5840880..d3177b1 100644 --- a/sources/modules/compilation-model/separate-compilation.md +++ b/sources/modules/compilation-model/separate-compilation.md @@ -68,7 +68,7 @@ implementation-defined, unspecified, or undefined behavior._ * Compilation on a single commandline versus using multiple commands. * What needs to be recompiled if only a function is altered? Altered in use syntax versus altered only in semantics. -### Main: implementing +### Main: Command of supporting mechanisms and tools #### Background/Required Knowledge From 61c29b70608544ee83dc2bb408730340181295eb Mon Sep 17 00:00:00 2001 From: Victor Eijkhout Date: Thu, 31 Oct 2024 10:53:32 -0500 Subject: [PATCH 20/25] Update separate-compilation.md caption improved --- sources/modules/compilation-model/separate-compilation.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/sources/modules/compilation-model/separate-compilation.md b/sources/modules/compilation-model/separate-compilation.md index d3177b1..8421d0c 100644 --- a/sources/modules/compilation-model/separate-compilation.md +++ b/sources/modules/compilation-model/separate-compilation.md @@ -91,7 +91,7 @@ A student should be able to: * Cover the mechanisms for include and library paths to your own code, as well as discovery mechanisms for external libraries. -### Advanced +### Technicalities and tools _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._ From 3a05bb1a00a9bda6797cdc2ad2bda11eb726bffe Mon Sep 17 00:00:00 2001 From: Victor Eijkhout Date: Thu, 31 Oct 2024 10:54:58 -0500 Subject: [PATCH 21/25] Update separate-compilation.md itemize --- sources/modules/compilation-model/separate-compilation.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/sources/modules/compilation-model/separate-compilation.md b/sources/modules/compilation-model/separate-compilation.md index 8421d0c..9b40736 100644 --- a/sources/modules/compilation-model/separate-compilation.md +++ b/sources/modules/compilation-model/separate-compilation.md @@ -96,10 +96,10 @@ A student should be able to: _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._ -1. Language inter-operability: the `extern "C"` mechanism. -2. Linker conventions including name mangling. -3. The `nm` tool for inspection object files and libraries, including de-mangling. -4. Understand the issues involved in deciding between include guards and `#pragma once`. +* Language inter-operability: the `extern "C"` mechanism. +* Linker conventions including name mangling. +* The `nm` tool for inspection object files and libraries, including de-mangling. +* Understand the issues involved in deciding between include guards and `#pragma once`. [1]: ../object-model/declarations.md [2]: ../object-model/definitions.md From 996a433bc263b62bf4427705adf76606d63bc3d5 Mon Sep 17 00:00:00 2001 From: Victor Eijkhout Date: Thu, 31 Oct 2024 11:02:05 -0500 Subject: [PATCH 22/25] Update separate-compilation.md proposal --- sources/modules/compilation-model/separate-compilation.md | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/sources/modules/compilation-model/separate-compilation.md b/sources/modules/compilation-model/separate-compilation.md index 9b40736..ac34b36 100644 --- a/sources/modules/compilation-model/separate-compilation.md +++ b/sources/modules/compilation-model/separate-compilation.md @@ -85,7 +85,11 @@ A student should be able to: #### Caveats -1. Build systems make things both easier and harder. +* Build systems make things both easier and harder. + * Student does not have to set include/library paths. + * Build systems prevent unnecessary recompilation. + * Build systems have a separate learning curve. + * Build systems will pay off when using libraries, less with self-contained student code. #### Points to cover From 0635d333ad768ea905d2d24d6535e5cc2ccf0600 Mon Sep 17 00:00:00 2001 From: Victor Eijkhout Date: Thu, 31 Oct 2024 11:03:48 -0500 Subject: [PATCH 23/25] Update separate-compilation.md TOC in sync with captions --- sources/modules/compilation-model/separate-compilation.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/sources/modules/compilation-model/separate-compilation.md b/sources/modules/compilation-model/separate-compilation.md index ac34b36..5f27e35 100644 --- a/sources/modules/compilation-model/separate-compilation.md +++ b/sources/modules/compilation-model/separate-compilation.md @@ -11,11 +11,11 @@ _Specifies the different levels of teaching._ ------------------------------------------------------------------------ Level Objective ----------------- ------------------------------------------------------ -Foundational: Awareness of the existence of separate compilation +Foundational: Basic use of separate compilation -Main: Awareness of supporting mechanisms and tools +Main: Command of supporting mechanisms and tools -Advanced: Awareness of technicalities and tools +Advanced: Technicalities and tools ------------------------------------------------------------------------ @@ -95,7 +95,7 @@ A student should be able to: * Cover the mechanisms for include and library paths to your own code, as well as discovery mechanisms for external libraries. -### Technicalities and tools +### Advanced: Technicalities and tools _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._ From 71a661231f46df6e5792a1c4bed583122de43227 Mon Sep 17 00:00:00 2001 From: Victor Eijkhout Date: Thu, 31 Oct 2024 11:10:48 -0500 Subject: [PATCH 24/25] Update separate-compilation.md added sentence about translation units --- .../modules/compilation-model/separate-compilation.md | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/sources/modules/compilation-model/separate-compilation.md b/sources/modules/compilation-model/separate-compilation.md index 5f27e35..4723393 100644 --- a/sources/modules/compilation-model/separate-compilation.md +++ b/sources/modules/compilation-model/separate-compilation.md @@ -78,10 +78,11 @@ implementation-defined, unspecified, or undefined behavior._ A student should be able to: -1. Use compile flags, including `-I` and `-L` to specify search paths. -2. Make header files for their own code, including using header guards. -3. Use include directives for the headers of external libraries. -4. Be able to declare `extern` variables. +1. Explain what a translation unit is, and its relation to header files. +2. Use compile flags, including `-I` and `-L` to specify search paths. +3. Make header files for their own code, including using header guards. +4. Use include directives for the headers of external libraries. +5. Be able to declare `extern` variables. #### Caveats From 7313ec4df5f9000c0cc841186ba0a663808b5fbe Mon Sep 17 00:00:00 2001 From: Victor Eijkhout Date: Thu, 31 Oct 2024 11:12:36 -0500 Subject: [PATCH 25/25] Update separate-compilation.md extern variable mention removed --- sources/modules/compilation-model/separate-compilation.md | 1 - 1 file changed, 1 deletion(-) diff --git a/sources/modules/compilation-model/separate-compilation.md b/sources/modules/compilation-model/separate-compilation.md index 4723393..160a43d 100644 --- a/sources/modules/compilation-model/separate-compilation.md +++ b/sources/modules/compilation-model/separate-compilation.md @@ -82,7 +82,6 @@ A student should be able to: 2. Use compile flags, including `-I` and `-L` to specify search paths. 3. Make header files for their own code, including using header guards. 4. Use include directives for the headers of external libraries. -5. Be able to declare `extern` variables. #### Caveats