Rearranging things, and adding some more early material, plus some highly advanced stuff.

Author: jrper

_toc.yml

@@ -20,11 +20,13 @@ sections:
   - file: part_three/01_pointers
   - file: part_three/02_structs
   - file: part_three/03_header_files
+  - file: part_three/04_build_systems
   - file: part_three/exercises_three
 - file: appendices/intro
   sections:
   - file: appendices/keywords
   - file: appendices/c-preprocessor
+  - file: appendices/combining_with_python
 - file: changelog
 - file: genindex
   title: Index

appendices/c-preprocessor.md

@@ -1,16 +1,25 @@
+```{index} C Preprocessor
+```
 # The C preprocessor
-```{index} C Preprocessor ```
+
 
 This page briefly describes the C preprocessor which is by default run on every file before compilation. The preprocessor modifies the text of the code which is seen by the actual compiler based on its own collection of commands, which are known as preprocessor directives. These commands can add, remove or change code in a number of ways and together act to simplify the process of making code run in multiple configurations or on multiple systems.
 
 ## Preprocessor directives.
 
 You have already seen some common preprocessor directives while working with :doc:`header_files`. The `#include` directive is one of the most commonly used and most visible C preprocessor directives, which "under the hood" directs the preprocessor to copy the entire (processed) text of another file into the file being worked on. Similarly, the `#pragma once` or `#if ndef ...` patterns are also directives, either explicitly commanding the preprocesser to only work on the file once, or generating the same effect using a preprocessor variable. The full(ish) list of possible standard directives is
 
-|#define |#elif|#else|#endif|
-|#error  |#if  |#ifdef|#ifndef|
-|#import |#include|#line|#pragma
-|#undef|#warning|||
+ 
+| Control Structures | Logging Controls | Others |
+|--------------------|---------|-------|
+| #if              | #error  | #define |
+| #elif| #warning |#pragma|
+| #else| | #include|
+| #ifdef | | #undef |
+| #ifndef | | #line |
+| #endif | | |
+
+
 
 ## Defining preprocessor macros
 
@@ -20,7 +29,7 @@ Beside `#include`, which appears in many C/C++ files, the conditional directives
 
 Any if-like block can optionally have an `#else` block attached to if. As with Python or C, the `#else` block matters (i.e. is passed to the compiler) if the first expression doesn't evaluate true, in which case it is compiled. These if blocks can be nested providing every block is terminated correctly.
 
-As a concrete example, consider the code block
+As a concrete example, consider the following code block:
 
 ```c++
 

appendices/keywords.rst

@@ -10,12 +10,15 @@ Storage keywords
 
 .. glossary::
 
-    auto
+    auto (C version)
         Declare variable which is automatically cleaned up when coming out of scope and is stored locally (i.e. exactly the default behaviour). *C++ behaviour is different*
+
     register
         *Suggests* to the compiler that the variable should be stored in a register rather than RAM. This allows fast access, but limits behaviour (e.g. it cannot be used with `&`).
+
     static
         Declare a variable which exists for the lifetime of the program.
+
     extern
         Declare a variable name which has memory storage assigned elsewhere.
 
@@ -26,34 +29,49 @@ Datatype keywords
 
     char
         One byte data type, often used to store text with ASCII encoding.
+
     const
         Qualifier indicating a variable will not change its value while it is in scope.
+
     double
         A double precision (i.e. usually 64 bit, 8 byte) floating point number. Directly equivalent to the Python `float` or `numpy` `float64`.
+
     enum
         Declare a list of names which are mapped to integer values (automatically, if manual values aren't given).
+
     float
         A single precision (i.e. usually 32 bit, 4 byte) floating point number. Equivalent to the `numpy` `float32`.
+
     int
         An integer (usually 4 bytes on modern systems). Equivalent to `numpy` `int32`.
+
     long
         By itself declares a long integer (usually 8 bytes on modern systems). Equivalent to `numpy` `int64`. Can also be used as a qualifier with `double` for 10 byte floating point number.
+
     restrict
+        Qualifier which indicates that a pointer is the only pointer which can access the memory it points to. This allows the compiler to make optimisations which would otherwise be unsafe.
 
     short
         A 2 byte integer. Equivalent to `numpy` `int16`.
+
     signed
         Qualifiers which declares integers to be signed (i.e take both positive and negative numbers). Default behaviour.
+
     struct
         Declares a combined data structure containing other datatypes as separate members.  
+
     typedef
         Declare an alias for a (possibly qualified) datatype.
+
     union
         Declares a combined data type containing other data types all sharing the same memory.
+
     unsigned
         Qualifier which declares integers to be unsigned (i.e. positive, ranging from 0 to the largest number which fits in the memory space).
+
     void
         Data type representing no specific sort of value.
+
     volatile
         Qualifier indicating that a value is liable to change at any time. Ensures the compiler will execute commands using the variable in the order they are written.
 
@@ -64,28 +82,40 @@ Control keywords
 
     break
         Exit the innermost loop (in the current scope) currently executing.
+
     case
         Declare one option in a `switch` statement.
+
     continue
         Skip to the next iteration of a loop.
+
     default
         Declare a default option for a `switch` statement.
+
     do
         Start a `do ... while` loop block.
+
     else
         Declare alternative behaviour for an `if` block, executed when the `if` statement is not true.
+
     for
         Declare a `for` loop.
+
     goto
         Jump to another labelled section of code (Use with great care).
+
     if
         Declare a conditional code block, which runs only when the test expression is true.
+
     inline
         Function specfier which *suggests* to a compiler that it places the relevant code directly in place, avoiding the overhead of a function call.
+
     return
-        Exit a function and pass any `return` value to the calling routine. 
+        Exit a function and pass any `return` value (which must be convertable to the specified data type) to the calling routine.
+
     switch
         Declare a `switch` block with multiple cases.
+
     while
         Either declare a `while` loop, or terminate a `do .. while` block.
 
@@ -115,29 +145,56 @@ Important keywords
 
 .. glossary::
 
-    auto
+    auto (C++ version)
         Declare a variable which automatically identifies its data type based on the context in which it is used. *Different from C behaviour*.
+
     bool
         Boolean datatype.
+
     catch
         Associate exception handlers with a `try` statement block, somewhat similar to Python.
+
     class
         Object oriented combined structure holding both data and functions, which usually act upon that data.
+
     delete
+        Delete a variable or object, and return the memory it was using to the operating system.
+
     false
-        Boolean data indicating a false value.
+        Boolean data indicating a false value. Opposite of `true`, and equivalent to `0`.
+
     friend
         Specifier indicating a function/class can access private or protected data stored in the declaring class.
+
     operator
         Declares an overloading of an operator for a user declared data type (i.e. lets the programmer use it with standard C++ operators such as `+` or `<<`).
+
     namespace
+        Declare a namespace, which is a way of grouping together related functions and classes (which acts a bit like a Python package/module).
+
     new
+        Allocate new memory for a variable, array or object, and return a pointer to it.
+
+    nullptr
+        A canonical pointer value (i.e. a pointer which points to nothing). Useful for initialising pointers or checking if a pointer is valid.
+
     private
+        Declare a class member which can only be accessed by functions within the class itself (i.e. not by functions outside the class which use an object of that class). Opposite of `public`.
+
     public
+        Declare a class member which can be freely accessed by functions outside the class which use an object of that class. Opposite of `private`.
+
     this
+        Pointer to the current object, which is passed implicitly to member functions. Useful for accessing other members of the same object if they have the same name as a local variable (e.g. a method argument).
+
     throw
+        Throw an exception, which can be caught by a `catch` statement. (Similar to Python `raise`).
+
     true
+        Boolean data indicating a true value. Opposite of `false`, and equivalent to `1`.
+
     virtual
+        Declare a virtual function, which can be overridden by a function of the same name in a derived class. Indicates that the function should be called based on the type of the object, rather than the type of the pointer to the object.
 
 
 

intro.md

@@ -18,5 +18,9 @@ Python is what is known as an interpreted language. To run code, you point a sin
 
 Python is also a garbage-collected language. It cleans up (eventually) all the memory you use to hold variables in your programs, once it realises you're no longer interested in them. C-like languages give you, as a programmer, more power & control on where in your computer memory things live, and how long they stay around for. In return, it is often the programmer's job to clean up once you have finished
 
-## Next Section - Getting Started
+## Summary
+
+In this section we have introduced the C & C++ programming languages, and given a brief motivation for why we might want to use them in preference to another language such as Python.
+
+In the next section we will look at how to compile and run C & C++ code on your own computer.
 

part_one/01_running.md

@@ -39,7 +39,7 @@ Here `g++` is the name of the linux GNU C++ compiler, the `-o` option specifies
 ## Compiling natively
 
 ### Windows: Visual Studio
-```{index} compiling:windows
+```{index} compiling:windows native
 ```
 
 For Windows users only, you can obtain the Microsoft C/C++ compiler by downloading the Visual Studio community package [here](https://visualstudio.microsoft.com/vs/community/). Visual Studio is a sister package to Visual Studio Code, which combines build tools for several programming languages along with an Integrating Development Environment (IDE) to code them in.
@@ -62,17 +62,17 @@ Most Mac users on th course will already have Homebrew installed, but for those
 brew install gcc
 ```
 
-will install a recent version of `gcc` as well as placing it in your standard path. Once installed, (and having openned a new terminal) you can confirm that things work by running the following command in a terminal
+will install a recent version of `gcc` (version 13 as of early December 2023) as well as placing it in your standard path. Once installed, (and having openned a new terminal) you can confirm that things work by running the following command in a terminal
 
 ```
-gcc-12 --version
+gcc-13 --version
 ```
 
 You should see a response something like
 
 ```
-gcc-12 (Homebrew GCC 12.2.0_1) 12.2.0
-Copyright (C) 2022 Free Software Foundation, Inc.
+gcc-12 (Homebrew GCC 13.2.0) 13.2.0
+Copyright (C) 2023 Free Software Foundation, Inc.
 This is free software; see the source for copying conditions. There is NO warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
 ```
 
@@ -83,7 +83,9 @@ g++-12 -o hello hello.cpp
 ./hello
 ```
 
-Here `g++-12` is the name of your new GNU C++ compiler, the `-o` option specifies the name of the output file (the default is `a.out`) and we must list the `.cpp` source file to compile into it. The second line then runs our new executable.
+Here `g++-13` is the name of your new GNU C++ compiler (version number 13), the `-o` option specifies the name of the output file (the default is `a.out`) and we must list the `.cpp` source file to compile into it. The second line then runs our new executable file which we have just compiled.
+
+Remember, we only need to compile once, and then we can run the executable as many times as we like. If we make any changes to the source code, we must recompile before we can run the new version and see the results.
 
 #### Xcode
 
@@ -115,7 +117,9 @@ c++ -o hello hello.cpp
 Here `c++` is the name of your C++ compiler, the `-o` option specifies the name of the output file (the default is `a.out`) and we must list the `.cpp` source file to compile into it. The second line then runs our new executable.
 
 
-### Linux
+### Linux/WSL: `gcc` or `clang`
+```{index} compiling:linux
+```
 
 Linux users are likely to find C compilers are either installed by default on most desktop distributions, or readily installable via the system package manager. Given the wide range of distributions in use, we can't hope to cover all of them, but for some of the more popular ones:
 

part_one/02_hello_world.md

@@ -1,8 +1,8 @@
 # Hello World!
 
-## Preface
+## Introduction
 
-Now that you have access to a working compiler, we'll move on to giving you some practical code to compile. A common first program for people to code in a new programming language is to write just enough code to print the phrase "Hello World!" to the screen (or other output device) and then exit.
+Now that you hopefully have access to a working compiler, and a place to writewe'll move on to giving you some practical code to compile. A common first program for people to code in a new programming language is to write just enough code to print the phrase "Hello World!" to the screen (or other output device) and then exit.
 
 The popularity of this tradition actually dates back to the beginnings of the C programming language in 1978 and the book "The C Programming Language" by Brian Kernighan and Dennis Ritchie.
 
@@ -32,11 +32,11 @@ _hello.c_:
     }
 ```
 
-Unlike Python, we need to use a function from outside the core language (in this case the function `printf` from the standard library `stdio`) in order to print our message to screen. At the compilation stage we do this with command `#include` (a C preprocessor directive), which in practice works somewhat similarly to the `import` statement in Python by pulling other code into our work.
+Unlike Python, we need to use a function from outside the core language, in this case the function `printf` from the standard library `stdio`, in order to print our message to screen. At the compilation stage we do this with command `#include`, a C preprocessor directive, which in practice works very similarly to the `import` statement in Python by pulling other code into our work.
 
-Where Python runs through commands beginning at the top of a script file, in `C` programs (at least, those printing to screen in the terminal) start at the beginning of the special `main` function. This function usually returns an integer, where `0` is taken to mean that things worked successfully, while other values are taken as a sign that something went wrong. 
+Where Python runs through commands beginning at the top of a script file, in `C` programs (at least, those printing to screen in the terminal) start at the beginning of the special `main` function. This function usually returns an integer, where `0` is taken to mean that things worked successfully, while other values are generally taken as a sign that something went wrong. 
 
-Finally, in C/C++ we **must** use the double quotes `"` to indicate a string (the `'` character won't work), and since the `printf` function doesn't end lines automatically, we must do it ourselves using the special end-of-line `\n` character.
+Finally, in C/C++ we **must** use the double quotes `"` to indicate a string (the `'` character won't work, and is only used with single characters), and since the `printf` function doesn't end lines automatically, we must do it ourselves using the special end-of-line `\n` "escape" character.
 
 ## Hello World in C++
 
@@ -52,17 +52,19 @@ _hello.cpp_:
     }
 ```
 
-You'll see that in this case, the code looks very similar to the C example. In fact, most C code is valid C++ code (possibly with a few small changes). The only thing that looks different is that rather than using a function like `printf` we are using the special `<<` operator (i.e. a token which works a bit like `+` or `-`) to send our message to `std::cout`, an "output stream" which in this case represents the screen.
+You'll see that in this case, the code looks very similar to the C example. In fact, most C code is valid C++ code (possibly with a few small changes). The only thing that looks different is that rather than using a function like `printf` we are using the special `<<` operator (i.e. a token which works a bit like `+` or `-`) to send our message to `std::cout`, an "output stream" which in this case represents printing to the screen.
 
-## Key differences from Python
+## Some key differences from Python
 
-1. Whitespace doesn't matter (although it still makes things easier to read when nicely formatted).
-2. Statements *must* end with a `;`.
-3. The code starts in the `main` function.
-4. Functions and variables have a fixed data type.
+1. Whitespace doesn't matter (although it still makes things easier to read when code is nicely formatted).
+2. Individual statements *must* end with a `;`.
+3. The code starts running at the top of the `main` function. There can only be one `main` in a given programme.
+4. Functions (and variables) have a fixed data type associated with them.
 
 
 ## Exercise: Run the Hello World programs
+```{index} Exercises: Hello World
+```
 
 Run the three different programs in Python, C and C++. You already know how to run Python scripts. You can look back to the previous section to see how to run C & C++ codes.