Merge pull request #166 from UCL/mm_updates2025

Mm updates2025

Author: mmcleod89

01projects/UsingTheTerminal.md

@@ -0,0 +1,45 @@
+---
+title: Terminal Commands Cheat Sheet
+---
+
+# Terminal Commands Cheat Sheet
+
+You will need to use the terminal on your machine every week for cloning code repositories, compiling code, and running executables. This page provides some of the most common commands that you will need to use in your terminal. Where you see angle brackets such as `<directory>` this means that this is an argument for a command, and should be replaced (in this example, with the name of a directory). 
+
+## Basic Terminal Commands
+
+- `pwd`: This displays the _present working directory_. This is where you currently are in the filesystem.
+- `cd <directory>`: This is _change directory_, and allows you to move to a different folder. Use `cd ..` to move up one level to the directory that contains the present working directory. You can go up multiple levels by `cd ../..` and so on. 
+- `ls`: This displays the contents of the current directory. You can write `ls <directory>` to display the contents of a directory that you are not in. If you write `ls -la` instead of just `ls` you will get more information, like when the file was created.
+- `mkdir <name>`: Creates a new directory with the given name. 
+- `cp <source> <destination>`: Copies a source file to a new destination. If the destination is a directory then it will copy the file into that directory and keep the name; if the destination includes a file name then the copy of the file will be given the new name.
+- `mv <source> <destination>`: The same as `cp` but it _moves_ the file instead of copying it. 
+- `rm <file>`: Remove (i.e. delete) a file.
+- `rm -rf <directory>`: Remove an entire directory.
+- `code <directory>`: Open a folder with VSCode. Use `code .` to open the current directory in VSCode. 
+
+## Git 
+
+- `git clone <repo>`: Clone a git repo.
+- `git add <file>`: Add a file to the current commit.
+- `git commit -m <message>`: Finalise a git commit with a given message.
+- `git checkout -b <branch_name>`: Create a new git branch.
+- `git push`: Push to the repository on the current branch.
+    - use `git push --set-upstream origin <branch_name>` if this is the first time using a new branch.
+- `git rm`: Delete a file and remove it from git tracking.
+- `git mv`: Move a file and update git tracking.
+
+## Compiling and Running Programs
+
+These commands are a quick reference for a number of tools that will be introduced over this course. They will be discussed more fully in their respective sections, so do not worry if you do not know what these are and do not expect to be able to use these right away. However, you may find it helpful to come back here to quickly look up useful commands. 
+
+- `g++ -o <output> -std=c++17 -I<include_directory> <sources>`: Compile a C++ program using the C++17 standard using `g++`. Use `-g` as well when you want to compile with debug symbols. 
+- `cmake -B <build_folder>`: Create a build folder and initialise cmake therein.
+- `cmake --build <build_folder>`: Build a CMake project in the build folder.
+- `./<path_to_executable>`: Run an executable. If the executable takes any arguments then place them after this, e.g. `./my_exe 5 10`.  
+- `gdb <path_to_exe>`: Run an executable in command line debugger (Ubuntu/WSL).
+- `valgrind ./<path_to_exe>`: Run an executable with valgrind. 
+- `g++ ... -fopenmp`: Compile with OpenMP turned on. (Other arguments omitted for brevity.)
+- `OMP_NUM_THREADS=<n_threads> ./<path_to_executable>`: Run an OpenMP program with a given number of threads. (Arguments can be supplied after the exe.)
+- `mpic++ -o <output> -std=c++17 -I<include_directory> <sources>`: Compile a C++ MPI program.
+- `mpirun -np <n_proc> <path_to_exe>`: Run an MPI program with a given number of processes. (Arguments can be supplied after the exe.)

01projects/index.md

@@ -13,6 +13,7 @@ In this section we also provide notes on how to use the **command line terminal*
 - [Introduction to C++ and "Hello World" Program](./sec01IntroToCpp.html)
 - [Further C++ Syntax](./sec02CppSyntax.html)
 - [C++ Programs with Multiple Files](./sec03MultipleFiles.html)
+- [Terminal Commands Cheat Sheet](./UsingTheTerminal.html)
 - [Version control with Git](./sec05Git.html)
 
 ## Useful References

01projects/sec01IntroToCpp.md

@@ -70,7 +70,7 @@ Here's a little snippet of C++:
 ```cpp
 #include <iostream>
 
-using namespace std;
+using std::cout;
 
 int main() 
 {
@@ -117,16 +117,23 @@ We'll go into what *exactly* this line is doing later but all you need to know a
 
 The next line is a *using statement*:
 
+```cpp
+using std::cout;
+```
+
+Classes (types of object) and functions from the standard library are prefaced with `std::`. This is called a _namespace_; it's used to avoid name clashes in large programs, and the standard library especially has a large amount in it with common names like `vector`, `map`, and `array` that could easily be used in other ways by other libraries or parts of your program! If you want to avoid writing `std::` all the time, you can use the `using` to make the class or function available without namespacing. You can also import an entire namespace, for example:
+
 ```cpp
 using namespace std;
 ```
 
-Again, we'll explore what this whole line actually does later but the short version is it allows us to access functions and classes inside the standard library without typing `std::` everywhere. I recommend you use it but **only in .cpp files**.
+This can avoid writing lists of `using` statements but runs the risk of name clashes. It's not usually good practice to import the entire `std` namespace because the potential for clashes is high, although it can be fine for small programs. 
 
-There's also an interesting bit of punctuation here; you have probably noticed the line ends in a semicolon `;`. C++, and many other languages, require this because the language doesn't care about (most) *whitespace*. Technically we can write our whole program all on one line, ignoring all indentation and newlines:
+There's also an interesting bit of punctuation here; you have probably noticed the line ends in a semicolon `;`. C++, and many other languages, require this because the language doesn't care about (most) *whitespace*. Technically we can write our whole program all on one line, ignoring all indentation and most newlines:
 
 ```cpp
-#include <iostream> using namespace std; int main() {cout << "Hello World!\n"; return 0;}
+#include <iostream>
+using namespace std; int main() {cout << "Hello World!\n"; return 0;}
 ```
 
 But this looks horrible so we use newlines and indentation in appropriate places to make our code more *readable*.

01projects/sec03MultipleFiles.md

@@ -217,3 +217,6 @@ If your include file is in a different folder, your need to tell the compiler wh
 g++ -o test_f main.cpp function.cpp -Iinclude_folder/
 ```
 
+### A note on `using` statements
+
+You should generally restrict your use of `using` statements to source (.cpp) files rather than header files. The reason for this is that the `using` statement will be imported along with the rest of your header, so any source file that includes your header will end up using that namespacing, and this can significantly increase the risk of clashes when you don't know where that header end up being imported!