Placing Code in Multiple Files

This topic is discussed starting on page 610 of the book.
- She mixes it with another topic.
- And I find students tend to confuse the two
- So I am going to cover it right now.
We tend to write huge programs professionally
- Look at this article: Linux In 2020: 27.8 Million Lines Of Code In The Kernel, 1.3 Million In Systemd
- Or this more generic article How Many Lines Of Code In Windows 10?
One way to manage this is to split code into different files.
This means
- We can build libraries so we can reuse code.
- We can allow different people to work on a project.
- We can organize our code so that it is easier to use.
- We can test different components of our code programatically.
What do we do?
- We split the "library" into two files
  - A Header file that ends in .h
  - This contains the function prototypes for the routines we wish to share.
  - This should probably contain some level of user documentation
  - An implementation file that ends in .C (or .cpp)
  - This is the full implementation of the functions.
  - This should contain implementation documentation
- We include the header in our file that uses the library
- We then use the compiler to generate object files.
- We use another part of the compiler, the linker to assemble the different object files into a single program.
An example
- I see that there are several string utilities that I would like to collect into a library.
  - Something to strip a string of all but the alpha characters
  - Something to change a string to all lower case characters
- I will probably see more as I use this, but these will do for now.
- But I will start by implementing StripString

Implementation

I create StringUtils.h
This contains the header for the function
And any header files I need

#include <string>
// this is bad and we will eventually remove this
using namespace std;

// this function removes all non alphabetic characters from a string
string StripString(string line);

There is one small problem,
- If we aren't careful, we might include this file more than once
- And this would lead to a redeclaration of the function.
- Which would make the compiler return an error.

The solution is to place a set of "guards"

We are really just programming in another language
The syntax is very simple and is always the same

#ifndef SOME_VARIABLE_NAME
#define SOME_VARIABLE_NAME

//code goes here

#endif

The variable name can be anything, but be careful
Look at /usr/include/limits.h
I chose DANS_STRING_UTILS

#ifndef DANS_STRING_UTILS
#define DANS_STRING_UTILS

#include <string>
// this is bad and we will eventually remove this
using namespace std;

// this function removes all non alphabetic characters from a string
string StripString(string line);

#endif

Then the implementation file

This is sort of a normal program file but
- You don't have a main routine
- You use #include "headerfile.h" in place of external function prototypes
  - Rules of thumb, they are a bit more complex but
  - #include < file> : search for file in the standard include locations
  - #include "file" : search for the file in the local directory

#include <iostream>

// this is good practice
#include "StringUtils.h"

// because we will remove it from the .h file
using namespace std;

// notice this matches the function prototype just like before
string StripString(string line) {
    size_t i;
    string rv;

    for(i=0;i<line.size();i++) {
       if (isalpha(line[i])) {
          rv += line[i];
       }
    }

    return rv;
}

Using the library

There is really no change here.

Include the header file

But it is in quotes, since it is local, not angle brackets.

#include <iostream>
#include <fstream>

#include "StringUtils.h"

using namespace std;

Call the code

   while (file and dictionarySize < MAX_WORDS) {
       dictionary[dictionarySize] = StripString(word);

The last bit: Compiling
- We need to compile the library
  - But we don't want to make an executable out of it.
  - So we use a compiler flag : -c
    - This says to compile but don't link
    - Or build an object file.
    - The convention is for this to be called filename.o
```
g++ -g -O3 -Wall -Wextra -Wuninitialized -pedantic -Wshadow -Weffc++ -Wunused   -c -o StringUtils.o StringUtils.C
                
```
- Then we compile the main, but link with the .o file
  - ```
   
  g++ -g -O3 -Wall -Wextra -Wuninitialized -pedantic -Wshadow -Weffc++ -Wunused    dictionary.C StringUtils.o   -o dictionary
          
```
- Note that StringUtils.o is included in the compile line.
- But this is too much for me to remember
  - Fortunately make takes care of this.
  - I added two lines to my Makefile
  - ```
  CXXFLAGS = -g -O3 -Wall -Wextra -Wuninitialized -pedantic -Wshadow -Weffc++ -Wunused
  
  all: dictionary
  
  dictionary: StringUtils.o
  
  StringUtils.o: StringUtils.h
  
  clean:
          rm -rf dictionary *.o
              
```
- This says:
  - To build dictionary I need StringUtils.o
  - And to build StringUtils.o I need StringUtils.h
- These are called dependencies