Makefile Tutorial

For Repeated Compilation

Makefile Example

Introduction

   Tired of having to type out a long-winded gcc command? Keep forgetting a pesky flag or two? Or maybe an entire source file nestled in your burstly project? Well there's a better way. You've probably used it before especially if you've downloaded some GitHub projects. Make. But how to use such untapped power? Many tutorials are pretty skimpy on details, or too overburdening to get the tangible facts. Perhaps this one is just right.

Features

  • Type once, compile ad infinitum (ℵ0 times to be exact).
  • Compatible with any *nix system (or those with make installed).
  • Usability with gcc, g++, gfortran, etc.
  • Ability to be customized by your users.

Demonstration

   Let's start with a 'dead' simple program which we wish to compile:

  1. #include <iostream>
  3. int main(int argc, char *argv[]) {
  4.     std::cout << "Goodbye, cruel world!" << std::endl;
  5.     return 0;
  6. }
More

   Typically we'd run: g++ -o Example.exe main.cpp to get our desired executable. But let's plan for the future as this is will be an expanding example. To run our make command, we need a target "Makefile". So let's make one (pun possibly intended):

  1. # Makefile for our example program (this is a comment)
  2. # V1.0
  4. Example.exe:
  5.     g++ -o Example.exe main.cpp
    6. More

   Now type make and presto. Makefiles are essentially recipes to create a certain object which can be object files (.o), library files (.dll), or the final executable(s) (.exe). In our case, we had one recipe, to make "Example.exe" and to create it, we run g++ -o Example.exe main.cpp. Try running make again. It should say that everything is up to date. Change the source file subtly and calling our one word command again results in a new compiliation. This will be important later. Let's add to this example to further our understanding. Since we're (I'm) writing this in C++, let's add a header file with an accompanying source file. Firstly, here's the new source and header files, "Parrot.hpp" (I wonder what it could do?!?), "Parrot.cpp" and the new "main.cpp":

  1. #ifndef PARROT_H
  2. #define PARROT_H
  4. #include <ostream>
  5. #include <string>
  7. // Give it a phrase and you'll never hear the end of it.
  8. class Parrot {
  9. public:
  10.     Parrot(std::string Phrase) : phrase(Phrase) {}
  11.     // Echoes the provided phrase to a given output stream
  12.     void Speak(std::ostream &os);
  13. private:
  14.     std::string phrase;
  15. };
  17. #endif
More
  1. #include <ostream>
  2. #include <string>
  3. #include "Parrot.hpp"
  5. // Echoes the provided phrase to a given output stream
  6. void Parrot::Speak(std::ostream &os) {
  7.     os << phrase << std::endl;
  8. }
More
  1. #include <iostream>
  2. #include "Parrot.hpp"
  4. int main(int argc, char *argv[]) {
  5.     Parrot avianBeing = Parrot("Polly isn't fond of crackers");
  6.     avianBeing.Speak(std::cout);
  7.     return 0;
  8. }
More

   Now back to our "Makefile":

  1. # Makefile for our example program
  2. # V1.1
  4. Example.exe: main.o Parrot.o
  5.     g++ -o Example.exe main.o Parrot.o
  7. main.o: Parrot.hpp
  8.     g++ -c main.cpp
  10. Parrot.o: Parrot.hpp
  11.     g++ -c parrot.cpp
  13. .PHONY: clean
  15. clean:
  16.     rm -f Example.exe main.o Parrot.o
More

   Jesus H. Christ slow down! Let's go through it bit by bit. Our original "Example.exe" recipe now has two dependencies: "main.o" and "Parrot.o", and the g++ command has adapted to these object files. But how do we make these dependencies? Just add another recipe! So there's one for "main.o" and "Parrot.o" from their respective source files. Let's ignore the ".PHONY" for the time being and move onto "clean". This recipe will remove the previous files that were created, allowing for a fresh start. When in doubt, call make clean to begin anew. This begs a question, if we can write make clean, then could we write make Example.exe? Indeed. You can choose which recipes you wish to follow if you desire. But as seen previously, if you make an edit in one of the files, make will compile those files that have changed, while leaving those that are up to date untouched. Very good. But this is actually quite verbose for a "Makefile" and can be shortened quite a bit. Take 3!

  1. # Makefile for our example program
  2. # V1.2
  4. CXX = g++
  5. OBJECTS = main.o Parrot.o
  7. Example.exe: $(OBJECTS)
  8.     $(CXX) -o $@ $(OBJECTS)
  10. main.o: Parrot.hpp
  11. Parrot.o: Parrot.hpp
  13. .PHONY: clean
  14. clean:
  15.     $(RM) Example.exe $(OBJECTS)
More

   We now introduce variables into the mix. We list the dependencies of "Example.exe" as a variable, which is previously initialized to all our desired object files. Additionally we added "$(CXX)" to allow our user to change up the compiler if they really want to (most likely not). Instead of explicitly writing in "Example.exe" after the -o flag, we can write "$@" which refers to the name of the recipe, namely "Example.exe". Savings. Finally in our "clean" recipe, we have a "$(RM)", which would expand to "rm -f". But what's with the lack of instructions with our object files? Don't we need those? Actually make is smart. It assumes (correctly) that you're going to call $(CXX) -c main.cpp and so forth. So why bother to write it? This reduces clutter, allowing one to see easily just the dependencies for each object file. For simple programs, this format should suffice. But for a more complicated architecture, you'd want to pass some more flags into our compiler. So let's explore that. This next bit uses Boost, which expands C++'s paultry library. Ah its one major downside. Anyways, I'll be using the Program Options and Filesystem libraries as to add some nice command line support. Here's the revised "main.cpp" for reference (don't bother to understand, just note the include's):

  1. #include <iostream>
  2. #include <string>
  3. #include <vector>
  4. #include <boost/filesystem.hpp>
  5. #include <boost/program_options.hpp>
  6. #include "Parrot.hpp"
  8. namespace {
  9.     const int SUCCESS = 0;
  10.     const int ERROR_IN_COMMAND_LINE = 1;
  11.     const int ERROR_UNHANDLED_EXCEPTION = 2;
  12. }
  14. namespace po = boost::program_options;
  16. int main(int argc, char *argv[]) {
  17.     try {
  18.         int osType;
  19.         std::vector<std::string> phrases;
  21.         // Add additional arguments
  22.         po::options_description desc("Options");
  23.         desc.add_options()
  24.             ("help,h", "Display help")
  25.             ("output_stream,o", po::value<int>(&osType)
  26.                 ->value_name("INT")->default_value(1),
  27.                 "1 for STDOUT, 2 for STDERR")
  28.             ("phrase", po::value< std::vector<std::string> >(&phrases)
  29.                 ->multitoken()->composing()->required(),
  30.                 "Phrase to be parroted back")
  31.         ;
  33.         // Add positional arguments
  34.         po::positional_options_description positional;
  35.         positional.add("phrase", -1);
  37.         // Set up variable map
  38.         po::variables_map vm;
  39.         try {
  40.             po::store(po::command_line_parser(argc, argv).options(desc)
  41.                       .positional(positional).run(), vm);
  43.             // Check help first in order to exit
  44.             if (vm.count("help")) {
  45.                 std::string exe = boost::filesystem::basename(argv[0]);
  46.                 std::cout << "USAGE: " << exe << " [options] <phrase>...\n\n"
  47.                           << desc << std::endl;
  48.                 return SUCCESS;
  49.             }
  51.             // Parse arguments and check constraints
  52.             po::notify(vm);
  53.         } catch (po::required_option &e) {
  54.             std::cerr << "Missing required option.\nTraceback:\n"
  55.                       << e.what() << std::endl;
  56.             return ERROR_IN_COMMAND_LINE;
  57.         } catch (po::error &e) {
  58.             std::cerr << "An unexpected argument parsing error occurred.\n"
  59.                       << "Traceback\n" << e.what() << std::endl;
  60.             return ERROR_IN_COMMAND_LINE;
  61.         }
  63.         // Check our arguments
  64.         if (vm.count("output_stream")) {
  65.             if (osType < 1 || osType > 2 ) { // Not STDOUT or STDERR
  66.                 std::cerr << "Output stream is neither STDOUT or STDERR, "
  67.                           << "exiting" << std::endl;
  68.                 return ERROR_IN_COMMAND_LINE;
  69.             }
  70.         }
  72.         // Compile our phrase
  73.         std::string phrase = "";
  74.         for (std::vector<std::string>::iterator it = phrases.begin();
  75.              it != phrases.end();
  76.              it++)
  77.         {
  78.             if (phrase == "") {
  79.                 phrase = *it;
  80.             } else {
  81.                 phrase += " " + *it;
  82.             }
  83.         }
  85.         // Let our pet speak
  86.         Parrot avianBeing = Parrot(phrase);
  87.         avianBeing.Speak((osType == 1) ? std::cout : std::cerr);
  88.         return SUCCESS;
  90.     } catch (std::exception &e) {
  91.         std::cerr << "An unexpected error in main occurred.\nTraceback:\n"
  92.                   << e.what() << std::endl;
  93.         return ERROR_UNHANDLED_EXCEPTION;
  94.     }
  95. }
More

   Kinda overkill just to add one option (whether to parrot to STDOUT or STDERR) and one positional argument (what phrase we want to parrot). To be honest, don't worry about understanding any of it; it's just meddling with syntax. But one question remains. How do we compile it? Boost requires the use of a dynamically linked library (.dll) on Windows systems or a shared object (.so) on MacOS(?) or Linux platforms. So this will require the -l flag. IMPORTANT NOTE: Remember when using the -l flag to remove the starting "lib" part and the extension (i.e. libboost_program_options.so -> boost_program_options). But where can we find this file? You may have to a bit of searching (like I did). I personally found mine at "/usr/lib/x86_64-linux-gnu" on a Ubuntu 64 bit machine but yours may be different (and your users).

  1. # Makefile for our example program
  2. # V1.3
  4. DEBUG = -g
  5. CXX = g++
  6. CXXFLAGS = -Wall $(DEBUG)
  7. LDFLAGS = -L/usr/lib/x86_64-linux-gnu \
  8.           -lboost_filesystem \
  9.           -lboost_program_options \
  10.           -lboost_system
  11. OBJECTS = main.o Parrot.o
  13. all: Example.exe
  15. Example.exe: $(OBJECTS)
  16.     $(CXX) -o $@ $(OBJECTS) $(LDFLAGS)
  17. main.o: Parrot.hpp
  18. Parrot.o: Parrot.hpp
  20. .PHONY: all clean
  21. clean:
  22.     $(RM) Example.exe $(OBJECTS)
More

   We add some additional flags to be passed by "$(CXX)", namely those in "$(CXXFLAGS)" and "$(LDFLAGS)". We allow for debugging (using -g which can be switched off by leaving "DEBUG" blank), to witness all warnings (using -Wall), to show where the location of where our .so files are (using -L), and the library files themselves (using -l, sneaky boost/filesystem.hpp requires both libboost_filesystem.so and libboost_system.so). IMPORTANT NOTE: the "$(LDFLAGS)" must as the last argument for "$(CXX)" or else you'll get an error... took me too long to find this one out! So where's "$(CXXFLAGS)" in this compilation command? Well make has a slew of default variables that it uses implicitly (see Implicit Variable Rules for too much info). If you do run this Makefile, you'll see the -Wall and -g flags are indeed used. The new "all" recipe is meant to be for projects with multiple executables, but we only have one sadly. When you run make, it is actually make all so you don't need to type the extra noun. Finally let's address ".PHONY". If you're extremely observant (maybe even more than Holmes), all our recipes had names that became a file. For example, the recipe "main.o" was created through the compilation of "main.cpp" into an object file. This is not a coincidence, but an integral part of make. The "clean" recipe does not create a file called "clean". So what happens if we had a file called "clean"? make would check the dependencies of the "clean" recipe, to which there are none, and conclude that the "clean" file is up to date. The instructions below would never execute and desired programs/object files would not be deleted. Oh dear. However, when we declare "clean" as a dependency to ".PHONY", this overrides the up-to-date-checking and allows its recipe to be conducted. To wrap up, here's a final overview of the commands and showcase of the program we've built:

  1. make
  2. g++ -Wall -g   -c -o main.o main.cpp
  3. g++ -Wall -g   -c -o Parrot.o Parrot.cpp
  4. g++ -o Example.exe main.o Parrot.o -L/usr/lib/x86_64-linux-gnu -lboost_filesystem -lboost_program_options -lboost_system
  5. ./Example.exe -h
  6. USAGE: Example [options] <phrase>...
  8. Options:
  9.   -h [ --help ]                   Display help
  10.   -o [ --output_stream ] INT (=1) 1 for STDOUT, 2 for STDERR
  11.   --phrase arg                    Phrase to be parroted back
  13. ./Example.exe -o 2 Open the pod bay doors, HAL
  14. Open the pod bay doors, HAL
  15. make clean
  16. rm -f Example.exe main.o Parrot.o
More

   Hopefully this tutorial gave you enough insight into Makefiles in order to write one of your own. There is _much_ more to this utility, such as wildcard characters, conditional expressions, functions, etc. but I won't go into them (because I don't quite need that complexity for my needs just yet). If you're curious, take a gander: Make Manual.