Using .h/.cpp files

This page covers using header files (.h) and implementation files (.cpp) to organize your code into multiple files. It assumes you are using a Chemeketa project template.

1. Add new files to the project folder and name them something like functions.h and functions.cpp. You can add files by right-clicking the project folder in the file explorer and selecting "New File" or by using the command palette (Ctrl+P or Cmd+P) and typing the new file name.

2. Open up your .h file and add this to declare some functions:

   #ifndef FUNCTIONS_H  // Change to a unique name based on your file name
   #define FUNCTIONS_H  // Change to match the above
   
   // Need to include <string> to use strings in function declarations
   #include <string>
   
   // Don't use 'using namespace std;' in header files
   
   /** @brief Example function declaration
    *  @return the number 42
    */
   int getAnswer();
   
   /** @brief Function that returns a greeting
    *  @return "Hello, World!"
    */
   std::string getGreeting();
   // use std::string because we didn't do 'using namespace std;'
   
   #endif
   

   Then add this code to your .cpp to define the functions:

   #include "functions.h"    // Include the .h file
   // Always use " " for your own header files, not < >
   
   // Don't need to include <string> here because it's included in the .h file
   
   using namespace std;  // OK to use in .cpp files
   
   // Define the functions declared in the .h file
   
   int getAnswer() {
     return 42;
   }
   
   string getGreeting() {
     return "Hello, World!";
   }
   

3. To use your functions in main.cpp, we must include the header file to get the function declarations:

   #include <iostream>
   #include "functions.h"    //Include your .h file
   
   using namespace std;
   
   int main() {
     cout << getGreeting() << endl;
     cout << "The answer is " << getAnswer() << endl;
   }
   

4. Try building and running the program. It will fail because the new .cpp file is not being compiled and linked into the program yet.

5. Open a terminal window and do this to compile the program manually:

   g++ -std=c++20 main.cpp functions.cpp -o program.exe
   

   That should work. We are explicitly saying to compile both main.cpp and functions.cpp. Then run it with:

   ./program.exe
   

6. To make sure the new .cpp file is included when you build the program using VSCode, open up the Makefile and find the line that starts with SHARED_FILES. Add your new .cpp file to that line so it looks like:

   SHARED_FILES = functions.cpp
   

   If you look further down in the Makefile, you will see that SHARED_FILES is included when compiling both the main program and the unit tests.

   Then add the header file to the HEADERS line so it looks like:

   HEADERS = functions.h
   

   This will help the make utility identify that your program depends on the header file and needs to be recompiled if the header file changes.

7. Now build and run the program using VSCode's Run and Debug feature. It should work correctly now. If not, see the list of common issues at the bottom of this page.

8. To use the functions in your tests.cpp, we need to include the header file in them as well. Remove the existing sample functions and test code from tests.cpp (leave the part that sets up doctest).

   Then add this below the doctest setup code:

   
   #include "functions.h"    //Include your .h file
   
   TEST_CASE( "test setup" ) {
     CHECK( getAnswer() == 42 );
     CHECK( getGreeting() == "Hello, World!" );
   }
   

9. Build and run the tests using VSCode's Run and Debug feature to confirm that program also works. If not, see the list of common issues at the bottom of this page. To compile the tests manually, do this in the terminal:

   g++ -std=c++20 tests.cpp functions.cpp -o tests.exe
   

   Then run the tests with:

   ./tests.exe