Makefile Tutorial | Chemeketa CS

Building Multiple Programs

Mon, 01 Jan 0001 00:00:00 +0000

This guide shows how to use one makefile to build multiple programs from one code base. For example: you have code that is for a unit test project and code that is for your main program. You can't compile it into one program as the tests and "main" program each define a main function. So you need to build two separate programs.

These instructions are based on the MakeComplex project from Week01 in the CS260 code repository. Use it if you want to be able to follow along exactly. The instructions assume you have a terminal open in that directory.

Examine the code in MakeComplex. There are two separate files with main functions - programA.cpp and programB.cpp. Those represent two separate programs that both happen to use code from Answer.cpp. We need to build the two files into two separate programs.
Create a file called Makefile and start with a basic set of targets for programA.
```
programA.exe: programA.cpp Answer.cpp Answer.h Templated.h
g++ -g -Wall -o programA.exe programA.cpp Answer.cpp
.PHONY: clean
clean:
rm -f programA.exe
```
As before, the target is named after the program to build, and it depends on all of the source files, both .cpp and .h, that I might want to edit and would require the program to be rebuilt if I did. The commands use g++ and list all of the .cpp files (but not .h files) to be compiled.

Add a rule for programB.

.PHONY: programA.exe
programA.exe: programA.cpp Answer.cpp Answer.h Templated.h
g++ -g -Wall -o programA.exe programA.cpp Answer.cpp
.PHONY: programB.exe
programB.exe: programB.cpp Answer.cpp Answer.h Templated.h
g++ -g -Wall -o programB.exe programB.cpp Answer.cpp
.PHONY: clean
clean:
rm -f programA.exe programB.exe

The two .exe rules are similar, but note that each program only uses its own .cpp file that defines main. They both use the shared files such as Answer.cpp.

Normally make just runs the first rule it finds. So if you type make, only programA.exe will be built. To build programB.exe, you will have to do:

make programB.exe

If you want to easily be able to make both program at once, you can add a phone all rule as the first one. It lists programA.exe and programB.exe as prerequisites - so those rules will be invoked automatically as part of building all. The all rules itself does not have any commands - all it does is trigger both program rules to run.

Since all is the first rule, it is the one that runs if you run make with no arguments. You can always run just make programA.exe or make programB.exe if you want to specify just one.
```
.PHONY: all
all: programA.exe programB.exe
.PHONY: programA.exe
programA.exe: programA.cpp Answer.cpp Answer.h Templated.h
g++ -g -Wall -o programA.exe programA.cpp Answer.cpp
.PHONY: programB.exe
programB.exe: programB.cpp Answer.cpp Answer.h Templated.h
g++ -g -Wall -o programB.exe programB.cpp Answer.cpp
.PHONY: clean
clean:
rm -f programA.exe programB.exe
```

Once any significant amount of information is shared, it becomes good practice to use variables to move the repeated information to just one place. For example, we are going to want to pass the same flags to the compiler each time, so let's put that information into a variable.

CXXFLAGS = -g -Wall
.PHONY: all
all: programA.exe programB.exe
.PHONY: programA.exe
programA.exe: programA.cpp Answer.cpp Answer.h Templated.h
g++ $(CXXFLAGS) -o programA.exe programA.cpp Answer.cpp
.PHONY: programB.exe
programB.exe: programB.cpp Answer.cpp Answer.h Templated.h
g++ $(CXXFLAGS) -o programB.exe programB.cpp Answer.cpp
.PHONY: clean
clean:
rm -f programA.exe programB.exe

The new first line defines the variable, CXXFLAGS, and the commands can simply use its value as $(CXXFLAGS) instead of duplicating the list of flags. This is particularly useful once the list of flags you want to configure gets long.

We can also use variables to avoid repeating the shared file names.

CXXFLAGS = -g -Wall
PROGRAM_A_FILES = programA.exe
PROGRAM_B_FILES = programB.exe
SHARED_HEADERS = Answer.h Templated.h
SHARED_FILES = Answer.cpp
.PHONY: all
all: programA.exe programB.exe
.PHONY: programA.exe
programA.exe: $(PROGRAM_A_FILES) $(SHARED_FILES) $(SHARED_HEADERS)
g++ $(CXXFLAGS) -o programA.exe $(PROGRAM_A_FILES) $(SHARED_FILES)
.PHONY: programB.exe
programB.exe: $(PROGRAM_B_FILES) $(SHARED_FILES) $(SHARED_HEADERS)
g++ $(CXXFLAGS) -o programB.exe $(PROGRAM_B_FILES) $(SHARED_FILES)
.PHONY: clean
clean:
rm -f programA.exe programB.exe

With this sort of style, you can often control most things about the Makefile by editing variable definitions near the top, while the commands can sometimes get quite cryptic-looking but rarely require editing anyway.

Making A Simple Program

Mon, 01 Jan 0001 00:00:00 +0000

Instructions to build a simple makefile for a single program.

A makefile consists of a set of rules, each with 3 parts:

a target
a list of prerequisites
a list of commands

The general syntax for a rule is:

target: prerequisite-1 prerequisite-2 ...
command1
command2
...

The target and prerequisites are separated by a colon (:). The commands must be preceded by a tab (NOT spaces).

If a command is not preceded by a tab, you get an error message like this:
makefile:4: *** missing separator. Stop.
If you see this message it usually means you have spaces instead of tabs.

From the terminal, navigate to the folder that has the code you wish to make a Makefile for. The sample shown below uses the MakeBasics project from the CS260 code (should be cs260Code/Week01/MakeBasics/).
Using your text editor, make a file called Makefile in that directory. Make sure it does not have an extension (no .txt at the end).
To edit the Makefile, you must use a text editor editor that will NOT put spaces in when you type a tab. By default, many programming tools will convert a press of the tab key into spaces. VSCode should correctly handle tabs (unless you have changed the settings). To see if you have tabs or spaces in VSCode, use View > Command Pallette and then View: Toggle Render Whitespace. Spaces will show as individual .s while tabs show as → followed by blank space.

Alternatively, you can use a simple text editor:
- Windows: Notepad
- Mac: Textedit (see these instructions for switching to plain text mode)
In the Makefile put the following:
```
.PHONY: program.exe
program.exe: main.cpp Answer.cpp Answer.h
g++ -g -Wall -o program.exe main.cpp Answer.cpp
```
- .PHONY: program.exe is a way to tell make that we always want make to run the commands when this target is invoked. Normally, make would try to figure out if program.exe actually needs to be rebuilt by comparing its date to that of its prerequisites. Normally, you might not declare program.exe as PHONY to prevent unnecessary rebuilds - especially if working on a large project where builds could take many minutes. However, always rebuilding is a nice way to make sure that your code ALWAYS gets rebuilt when you run make (which is essential if you are doing something like switching back and forth from Windows to Linux while developing.)
- The next line - the first required one - defines the target program.exe. A target that builds a file is typically given a name that matches the file it builds.
- After the : on that line, it lists three prerequisite files. These files must exist to run the rule. (If they are missing, make will try to build them using rules that match their names or, if those are not available, fail the build). If the rule is not declared .PHONY, the prerequisites also will be used to determine if the target is up to date and thus the build can be skipped.
- The next line is the command to run. This command builds the file program.exe using g++
  - -g says to include debugging info. This helps if you use Valgrind on this project
  - -Wall says to mention ‘all’ warnings
  - -o program.exe gives the output file the correct name
  - main.cpp Answer.cpp are the list of files that need to be compiled
Note that you should not list the .h files in the list of files to be compiled. They are not compiled, they are included into the .cpp files as appropriate. Any .h files you might edit should be listed in the prerequisites, but only there.

Save the Makefile.
Continuing in the terminal, type:
```
make
```
The default behavior for make is to run the first target in the file. In this, case that is the target program.exe. You can also run a particular rule by calling it explicitly.
```
make program.exe
```
Now type:
```
./program.exe
```
To run the program program.exe which is in the current directory (.). In general, this is how you will want to run your programs.
Usually, people add some additional rules to every makefile with some common behavior. These are called ‘phony’ rules, because they are not named after a file they produce but just given convenient names. You always should use .PHONY for these rules.

Add a rule to clean up, leaving the Makefile
```
.PHONY: program.exe
program.exe: main.cpp Answer.cpp Answer.h
g++ -g -Wall -o program.exe main.cpp Answer.cpp
.PHONY: clean
clean:
rm -f program.exe
```
The all target should come first, so that running make with no arguments builds everything by default. The all target simply depends on all of the files you want to make sure are always up-to-date, and does not need a recipe. The clean target doesn't have any prerequisites, so it always runs, and it deletes files created by the build process. It uses rm to remove files, and the -f option means that it won't ask for confirmation or complain if the file(s) already don't exist.

Note that rm is a Linux/MacOS command. The clean rule will not work if run in Windows. (To work in Windows it would have to execute the command del program.exe)
Now if you run make clean, you should end up with only your source files and not the compiled program.
You can rebuild the program with make or make all. If you try to rebuild it after the program has already been built and there are no changes to the source files, make will detect that nothing needs to be done.

Setup

Mon, 01 Jan 0001 00:00:00 +0000

You will need some code to test out these instructions with. If you grab the CS260 examples code, it has some projects in Week01 you can use to do so with. From a command prompt you can do this to grab a copy of the CS260 code:
```
git clone https://github.com/ChemeketaCS/cs260Code.git
```
If you are using Linux or Mac, you should be good to go. If you are using Windows you have two options:

A. Run everything inside of Windows Subsystem for Linux. This is preferable, especially if you also will be using Valgrind in WSL.

B. Use Windows PowerShell or Command Prompt, but type mingw32-make instead of make.